Distribution and Releases
Do not stop at npm run dev. Ship the CLI.
Beltline starts generated CLIs with release-ready conventions: npm install path, single-binary build, shell completions, versioning, changelog, CI workflows, and private distribution patterns.
A CLI is not done until someone else can install it. Distribution is developer experience. Make updates boring before the first release.
The first install experience decides whether the CLI gets adopted.
A good internal CLI is useless if people cannot install it, update it, trust it, or run it in CI. Distribution is part of the product. Most CLI projects add it late, and it shows — broken installs on certain OS versions, missing completions, no update story, no way to tell whether a version is current.
Beltline starts with a release-ready project layout so the install path exists before v1 does.
Before and after Beltline
| Before | After Beltline |
|--------|----------------|
| Local-only CLI that runs from a clone | Repeatable release workflow from CI |
| Release notes written by hand on a Friday | Changelog generated from changesets |
| No shell completions | acme completion zsh shipped on day one |
| Broken installs across macOS, Linux, Windows | acme doctor reports the actual problem |
| No update conventions | Versioned releases and acme update |
| Public-only release tooling | Private distribution paths supported out of the box |
Release workflow
acme --version
acme completion zsh
acme update
acme doctor
Release automation:
pnpm changeset
git push --tags
Generated distribution surfaces:
- npm package for developer installs
- Single-file binary via Bun for installs without a Node runtime
- Homebrew tap placeholder for macOS users
- Install script for internal distribution from S3 or an artifact store
- Shell completions for bash, zsh, and fish
- Changelog generated from changesets
What Beltline handles for you
Install paths users expect Generated projects support npm install, script install, and binary distribution. Users pick the path that matches their environment.
Completions for real terminal UX Shell completions for bash, zsh, and fish are generated from the command definitions. No manual writing, no drift from the actual commands.
Doctor command for support
acme doctor checks the environment, validates config, verifies connectivity, and reports version info. Reduces support load on day one.
Release workflows from the start Changeset-based versioning, CI workflow templates, and a changelog convention are part of the project layout. Set up once; repeat forever.
Private distribution for internal tools First-class guidance for private registries, internal artifact stores, and company install scripts. You do not need a public npm release to distribute internally.
Frequently asked questions
Can we distribute internally only? Yes. Beltline is designed for private distribution. Publish to an internal registry, an artifact store, or distribute through an install script without any public release.
Does this support npm? Yes. The generated project is a standard npm package that can be published to any npm-compatible registry, including private ones.
Can we ship binaries? Yes. Beltline supports a single-file binary build via Bun alongside package-manager installs. Useful for internal tools where you want a predictable runtime on every machine.
Do we need to use Homebrew? No. The Homebrew tap placeholder is optional. If your team uses npm, the install script, or an internal package manager, that is enough.