/anvil

CLI Packaging and Distribution Reference

Purpose: Ship a CLI through the package managers users already trust (Homebrew, apt, dnf, npm, PyPI, cargo, go install), with cross-compiled binaries, signed artifacts, and a functioning update-check path. Get the first install right — fixing a broken release lives in users' shell history forever. Read when: Adding a pkg subcommand, authoring a Homebrew formula, generating deb/rpm, cross-compiling releases, signing binaries, or designing an update-check mechanism.

Scope Boundary

• Anvil pkg: packaging manifests, cross-compile matrix, signing/attestation, install scripts, update-checker design, distribution-channel selection.
• Builder (elsewhere): the business logic inside the CLI (packaging does not change behaviour).
• Anvil env: user-side install into their own dotfiles environment (brew install in a bootstrap workflow).
• Gear (elsewhere): CI pipeline that runs goreleaser/cross/napi-rs, uploads artifacts, dependency scans of the packaging toolchain itself.
• Launch (elsewhere): release versioning strategy (SemVer/CalVer), changelog authoring, rollout plan, feature-flag gating.

If the request is "build deb/rpm artifacts and publish a Homebrew formula" → pkg. If it is "pick next version number and write release notes" → Launch. If it is "wire goreleaser into GitHub Actions" → Gear (with pkg owning the manifest content).

Channel Selection Matrix

Ship at least two channels. Power users on macOS/Linux expect Homebrew + static tarball; server users expect deb/rpm.

Cross-Compile Toolchain

Pin the cross toolchain version in CI. "Latest" silently breaks when the base image rotates (GLIBC version bumps are the classic symptom — user installs on RHEL 8 fail).

Target matrix at minimum: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64. Produce both glibc and musl Linux builds for static-binary distribution.

Homebrew Formula Skeleton

class Myapp < Formula
  desc "One-line description under 80 chars"
  homepage "https://github.com/org/myapp"
  version "1.2.0"
  license "MIT"

  on_macos do
    on_arm do
      url "https://github.com/org/myapp/releases/download/v1.2.0/myapp-darwin-arm64.tar.gz"
      sha256 "..."
    end
    on_intel do
      url "https://github.com/org/myapp/releases/download/v1.2.0/myapp-darwin-amd64.tar.gz"
      sha256 "..."
    end
  end

  def install
    bin.install "myapp"
    generate_completions_from_executable(bin/"myapp", "completion")
    man1.install "myapp.1"
  end

  test do
    assert_match version.to_s, shell_output("#{bin}/myapp --version")
  end
end

generate_completions_from_executable (available in Homebrew) wires bash/zsh/fish completions automatically if the CLI implements the completion subcommand. Ship the man page or Homebrew's audit complains.

deb / rpm via nfpm

nfpm emits both formats from one YAML, avoiding per-distro boilerplate:

name: myapp
version: 1.2.0
maintainer: team@example.com
description: |
  CLI description.
license: MIT
section: utils
contents:
  - src: ./dist/myapp
    dst: /usr/bin/myapp
  - src: ./completion.bash
    dst: /usr/share/bash-completion/completions/myapp
  - src: ./completion.zsh
    dst: /usr/share/zsh/site-functions/_myapp
  - src: ./myapp.1
    dst: /usr/share/man/man1/myapp.1
deb:
  fields:
    Bugs: https://github.com/org/myapp/issues

Serve the repo from a signed apt/yum endpoint (cloudsmith, packagecloud, or self-hosted with GPG-signed metadata). curl | sudo apt-key add is deprecated — use /etc/apt/keyrings/myapp.gpg + signed-by= in the sources list.

Signing and Attestation

Publish checksums (SHA256SUMS) and their signature (SHA256SUMS.sig or .intoto.jsonl attestation) alongside every release. Users installing via curl | sh must be able to verify.

Install Script Best Practices

Curl-pipe-sh is the universal fallback. Make it safe:

#!/bin/sh
set -eu
# fail fast, fail loud — never `|| true`

REPO="org/myapp"
VERSION="${MYAPP_VERSION:-latest}"
OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
ARCH="$(uname -m)"
case "$ARCH" in
  x86_64|amd64) ARCH=amd64 ;;
  aarch64|arm64) ARCH=arm64 ;;
  *) echo "unsupported arch: $ARCH" >&2; exit 1 ;;
esac
# verify checksum, never skip

Rules:

1. set -eu at the top; never swallow errors.
2. Download checksum and signature; verify before extracting.
3. Install to $HOME/.local/bin unless root — no surprise sudo.
4. Print the exact install path and how to add it to PATH.
5. Re-runnable (idempotent) — second run must be a no-op, not "already exists" error.
6. Support MYAPP_VERSION=1.2.0 pinning and DRY_RUN=1.

Update-Checker Mechanism

Opt-in, async, privacy-preserving:

Never self-update binary files from the CLI — path-traversal, signing, and permissions all break. Delegate to the package manager (brew upgrade myapp, apt upgrade).

Anti-patterns

• Publishing to npm a package that contains compiled binaries for only one platform (breaks for every other user).
• curl | sudo bash install scripts that do not verify checksums — one compromised CDN hop owns every user.
• Hard-coding /usr/local/bin in install scripts (Apple Silicon Homebrew uses /opt/homebrew/bin).
• Shipping darwin/amd64 only and hitting Rosetta for ARM users (slow, and breaks signed-binary flows).
• Leaving debug symbols in the release binary (5x size for no user benefit; strip or use -s -w).
• Auto-updating the binary in place without signature verification.
• Forgetting to bump the formula version SHA — brew install pulls the old tarball silently.
• Running the update-check synchronously before the command's real work — adds network latency to every invocation.
• Emitting the update-check notice during --json output — corrupts the JSON stream.

Handoff

• To Launch: SemVer bump justification, changelog, rollback plan if artifacts are yanked.
• To Gear: goreleaser/cargo-dist/napi-rs CI workflow, secret wiring (signing keys, notarization creds), release trigger.
• To completion: completion install paths per package format.
• To config: default config path that deb/rpm post-install should create.
• To Sentinel (adjacent): supply-chain check — sign every artifact, publish SBOM, attest provenance.