Why Go CLIs Are Moving to npm: Cross-Platform Distribution Explained

The article opens with an observation: tools like Feishu CLI, esbuild, Prisma, and Turborepo — all written in Go or Rust — instruct users to install via npx or npm install -g. This is not coincidence but a mature engineering pattern that treats npm as a cross-platform app store.

Why npm for Native CLIs?

Before npm, distributing a cross-platform CLI required maintaining Homebrew formulas for macOS, .deb / .rpm /Snap for Linux, and Scoop/Chocolatey/Winget or manual .exe + PATH setup for Windows — each with separate review processes and update cadences. npm collapses this into a single workflow. Five concrete reasons:

Unified entry point : npm install -g or npx works identically on every OS; documentation stays one-liner.

npx zero-install : npx downloads to ~/.npm/_npx, executes, and with @latest always runs the newest version, reducing stale-version bug reports. Many CLIs use npx as a bootstrapper that then performs the real install.

User environment overlap : Node.js is near-ubiquitous on developer machines; leveraging it avoids Python virtual-env or pip permission hassles.

Free, mature infrastructure : npm Registry provides global CDN, strict semver, dist-tag ( latest, beta, etc.), rollback, and mirrors like npmmirror — eliminating self-hosted bandwidth and HA costs.

PATH handling : Global install creates symlinks (or .cmd / .ps1 wrappers on Windows) in npm's global bin directory, so users rarely hit /usr/local/bin permission errors.

Trade-off: users must have Node.js installed, making this suitable for developer tools, not general-audience software.

Three Packaging Patterns

Fat package : Bundle all platform binaries in one package. Pros: simplest, works offline. Cons: large package; every user downloads all platforms. Example: small tools, tutorials.

postinstall download : Package contains only JS; postinstall script fetches platform-specific binary from GitHub Releases. Pros: tiny package; binary hosted anywhere. Cons: requires network at install; --ignore-scripts breaks it. Example: Feishu CLI.

optionalDependencies sub-packages : One sub-package per platform; main package declares them as optional dependencies; npm installs only the matching one. Pros: no second download, fast, mirror-friendly, survives --ignore-scripts. Cons: must publish multiple packages; more complex release pipeline. Example: esbuild.

Feishu CLI Teardown

Feishu CLI ( @larksuite/cli) uses the postinstall pattern. Its wrapper consists of four pieces:

1. package.json — Entry & Constraints

{
  "name": "@larksuite/cli",
  "bin": { "lark-cli": "scripts/run.js" },
  "scripts": { "postinstall": "node scripts/install.js" },
  "os": ["darwin", "linux", "win32"],
  "cpu": ["x64", "arm64", "riscv64"],
  "engines": { "node": ">=16" },
  "files": ["scripts/install.js", "scripts/install-wizard.js", "scripts/run.js", "checksums.txt", "CHANGELOG.md"]
}

bin

maps the command to a JS launcher ( run.js), not the binary itself. postinstall hook triggers the downloader. os / cpu restrict supported platforms; unsupported machines fail at install time. files whitelist ensures no binaries ship in the npm package — only scripts and checksums.txt, keeping the tarball tiny.

2. GoReleaser — Build & Release Binaries

.goreleaser.yml

defines a matrix: CGO_ENABLED=0 (pure static, no system deps), targets darwin/linux/windows × amd64/arm64/riscv64, outputs uniformly named archives ( lark-cli-<ver>-<os>-<arch>.tar.gz, .zip for Windows) and a checksums.txt. GitHub Actions triggered by protected tags drives the release, with pre-checks (tag protection, no rebuild of published versions).

3. install.js — Postinstall Downloader

Flow: detect platform → map Node's win32 / x64 to Go's windows / amd64 → construct download URL (GitHub Releases primary, npmmirror fallback, respects npm_config_registry for corporate mirrors) → download via system curl (with legacy Windows curl compat) → verify SHA-256 against bundled checksums.txt → enforce host allow-list → extract binary to ~/.lark-cli/bin/.

4. run.js — Runtime Forwarder

Intercepts install subcommand : npx @larksuite/cli@latest install passes install to run.js, which launches the install wizard before the native binary exists — the bootstrapper pattern.

Lazy-load fallback : If binary missing (e.g., npx skipped postinstall or user used --ignore-scripts), run.js invokes install.js on-the-fly, then execFileSync with stdio: "inherit" to forward args and preserve exit codes.

Windows self-update fix : Running .exe cannot be overwritten; updater renames it to .old, and run.js checks/restores on next launch.

Summary:

GoReleaser → GitHub Release → npm package (scripts + checksums) → install-time download → runtime forward

.

Hands-On: Publish a Go HelloWorld to npm

Account Setup

Register at npmjs.com, verify email.

Enable 2FA (authenticator app recommended). npm login --registry=https://registry.npmjs.org/; verify with npm whoami.

Pick a scoped name (e.g., @yourname/hello-go-cli), confirm availability via npm view (404 = free).

Go Program & Cross-Compile

// main.go
package main
import ("fmt"; "os"; "runtime")
func main() {
  name := "world"
  if len(os.Args) > 1 { name = os.Args[1] }
  fmt.Printf("Hello, %s! (%s/%s)
", name, runtime.GOOS, runtime.GOARCH)
}

# build.sh
#!/usr/bin/env bash
set -e
mkdir -p bin
build() {
  GOOS=$1 GOARCH=$2 CGO_ENABLED=0 \
    go build -ldflags="-s -w" -o "bin/hello-$1-$2$3" .
}
build darwin  arm64
build darwin  amd64
build linux   amd64
build linux   arm64
build windows amd64 .exe

-s -w

strips symbol/debug info. Rust equivalent: cargo build --target <triple> or cross.

npm Package Files

// package.json
{
  "name": "hello-go-cli-demo",
  "version": "0.1.0",
  "description": "A hello world CLI written in Go, shipped via npm",
  "bin": { "hello-go": "run.js" },
  "files": ["run.js", "bin/"],
  "os": ["darwin", "linux", "win32"],
  "cpu": ["x64", "arm64"],
  "engines": { "node": ">=16" },
  "license": "MIT"
}

// run.js
#!/usr/bin/env node
const { spawnSync } = require('child_process');
const fs = require('fs');
const path = require('path');

const OS = { darwin: 'darwin', linux: 'linux', win32: 'windows' }[process.platform];
const ARCH = { x64: 'amd64', arm64: 'arm64' }[process.arch];
if (!OS || !ARCH) { console.error(`Unsupported platform: ${process.platform}-${process.arch}`); process.exit(1); }

const bin = path.join(__dirname, 'bin', `hello-${OS}-${ARCH}${OS === 'windows' ? '.exe' : ''}`);
try { fs.chmodSync(bin, 0o755); } catch (_) {}

const r = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' });
if (r.error) { console.error(r.error.message); process.exit(1); }
process.exit(r.status === null ? 1 : r.status);

Key points: stdio: "inherit" shares terminal for interactive output/colors; exit code propagated so scripts can detect failure.

Local Verify & Publish

bash build.sh
npm pack --dry-run          # inspect file list & size
npm install -g .            # local global install
hello-go npm                # → Hello, npm! (darwin/arm64)

Publish with granular access token (bypass 2FA):

npm config set //registry.npmjs.org/:_authToken=YOUR_TOKEN
npm publish --access public --registry=https://registry.npmjs.org/

Verify in clean dir: npx hello-go-cli-demo@latest 世界.

Post-Publish Maintenance

Version immutability : Same version cannot be overwritten; bump via npm version patch && npm publish.

Unpublish window : Only allowed shortly after publish; prefer npm deprecate for bad versions.

Dist-tags for canary : npm publish --tag beta; users try via npx pkg@beta; latest unaffected.

Automation : Use GitHub Actions on tag push; adopt npm Trusted Publishing or granular tokens, avoid long-lived high-privilege tokens.

Advanced Migration Paths

Feishu style : Keep only install.js in package; host binaries on GitHub Releases; verify with checksums.txt.

esbuild style : Publish per-platform sub-packages (e.g., hello-go-cli-demo-linux-x64); main package lists them in optionalDependencies; run.js uses require.resolve to locate the installed sub-package binary. npm installs only the matching one — no second download, immune to --ignore-scripts.

Pitfall Checklist

--ignore-scripts & corporate policies : Many orgs disable postinstall; run.js must have lazy fallback or switch to optionalDependencies.

China network : GitHub Releases unreliable; implement mirror fallback (npmmirror) and respect user's registry config.

Supply-chain security : postinstall downloading external files must verify checksums and restrict download domains.

Static compilation : Go needs CGO_ENABLED=0; otherwise musl-based Alpine fails. Rust can target musl.

Windows file locking : Running .exe cannot be replaced; rename to .old on update, restore on next launch.

macOS signing/notarization : Unsigned binaries blocked by Gatekeeper; Feishu's GoReleaser includes signing/notarization steps — worth the effort for public tools.

License & README in files : Whitelist often omits them; run npm pack --dry-run before publish.

Summary

For developer tools, npm delivers near-zero-cost cross-platform distribution + version management + zero-install execution . A few dozen lines of JS launcher buy unified install UX and minimal adoption friction. Three implementation routes: fat package for simplicity, postinstall download for size, optionalDependencies sub-packages for robustness . Feishu CLI exemplifies the second route with thorough engineering on verification, mirror fallback, lazy loading, and Windows update handling.

Source code: https://github.com/bigwhite/experiments/tree/master/npm-distribution/hello-go-cli