Packaging & Distribution

Publish to the channel that is native to your users' ecosystem first, and add a self-contained binary for everyone else. The table lists the channels of this page; each one has a section below.

For Rust tools, cargo install and the [package] metadata that crates.io needs are covered in the Rust Reference’s Cargo & Workspaces.

The flow from a tag to the channels is the same for every ecosystem: build once per platform, checksum and sign the outputs, publish them, then let each package manager point at the published files.

pipx installs and runs end-user Python applications in isolated environments: it creates a separate virtual environment for each application and exposes only its commands on the PATH, so a tool’s dependencies never collide with a project’s. pipx install installs a tool, pipx run executes the latest version temporarily without installing it, pipx upgrade updates it and pipx ensurepath fixes the PATH. uv offers the same model as uv tool: uv tool install installs, uvx is an alias for uv tool run, uv tool upgrade updates, and uv tool update-shell adds the executable directory to the PATH. Both work for any package that declares console-script entry points, which is what [project.scripts] does in the Python framework page.

Pin the version in anything an agent or a CI job runs (docsctl@0.1.0), so the tool cannot change under a working prompt. References: pipx and uv — Tools.

A Homebrew formula is a small Ruby file with a homepage, a license, the url and sha256 of a source or binary archive, an install method and a test do block. Formulae for your own tool live in a tap, a Git repository named homebrew-<name> under your account, so users install with brew install OWNER/tap/docsctl after a one-time brew tap. The Formula Cookbook asks for tests that need no user input and exercise real functionality rather than only --version or --help, and recommends brew audit --new --formula before submission.

The test block above uses the contract’s schema --json, which is read-only and never prompts, so it passes in the sandboxed test run. GoReleaser can generate and push the tap update on every release; its documentation lists Homebrew formula publishing as deprecated in favour of homebrew_casks, so check which one your GoReleaser version documents before adopting either. References: Homebrew — Formula Cookbook.

An npm package exposes commands through the bin field of package.json, either as a string (one command named after the package) or as an object mapping command names to files. The referenced file must start with #!/usr/bin/env node, otherwise it is not started with Node. A global install links the file into a directory on the PATH (a .cmd shim on Windows); a local install makes it available in node_modules/.bin, from where npx can run it.

Keep the entry file tiny so that start-up cost stays low, as described in Agent Ergonomics, and use npx docsctl@0.1.0 …​ (an exact version) when an agent runs the tool without installing it. Reference: npm — package.json bin.

JBang runs a single Java source file as a script: //DEPS comment lines declare Maven dependencies, and a #!/usr/bin/env jbang shebang line makes the file executable (see the JBang documentation for how to write it in a Java file). It needs a JDK and downloads one when none is available. jbang app install installs a script as a command, and jbang app list shows what is installed. JBang can also run a file from a URL or a Maven coordinate, and a catalog lets users run a published tool as jbang docsctl@OWNER; because that runs remote code, jbang trust exists to make the user authorise the source first.

JBang is a good way to hand a JVM tool to Java developers without a release pipeline; it does not remove the JVM start-up cost, which is what the next section addresses. Reference: JBang documentation.

GraalVM Native Image compiles a Java application ahead of time into a standalone executable. The documentation describes executables that use fewer resources than the JVM, start quickly and reach peak performance without warm-up, which is why native binaries are the usual default for a tool an agent calls many times; measure with the hyperfine commands on the Java page before choosing. Two constraints shape packaging. First, the closed-world assumption: the build analyses which code is reachable, so reflection, resources and dynamic proxies need metadata (picocli-codegen produces it for picocli commands, see the Java page). Second, the build needs the platform’s native toolchain, so you build on each target operating system and architecture (a CI matrix) rather than cross-compiling one artifact for all of them.

Run the contract tests of Testing CLIs against the native binary, not only against the JAR, because a missing metadata entry appears only in the native build. Publish one archive per platform and list its checksum. Reference: GraalVM Native Image.

cargo install compiles a crate that has a binary target and puts the executable in <root>/bin (by default $HOME/.cargo/bin, chosen with --root, CARGO_INSTALL_ROOT, install.root or CARGO_HOME). --locked uses the dependency versions from Cargo.lock, so the user builds what you tested; --path installs from a checkout, --git from a repository, and --force reinstalls over an existing binary.

Because it compiles on the user’s machine it needs a Rust toolchain and takes a while, which suits Rust developers and not CI runners or agent sandboxes. Publish prebuilt archives too, and let cargo install be the fallback. Reference: cargo install.

The Windows Package Manager installs from manifests: YAML files that follow the manifest schema and live in the community repository (microsoft/winget-pkgs). A manifest names the PackageIdentifier (the Publisher.Package form), PackageVersion, publisher, licence and description, and one or more installers with an architecture, an installer type, the InstallerUrl and its InstallerSha256. The wingetcreate utility (wingetcreate new) prompts for the values, and can submit the pull request for you.

The single-file form is valid only for one installer and one locale; use the multi-file form otherwise. winget accepts installers only in its list of supported formats and requires silent installation, so check the current list on the winget documentation and choose the installer type for a command-line tool from it; a plain executable is rarely the right shape for one. GoReleaser has a winget section that generates the manifest and opens the pull request from your release. References: Windows Package Manager — submit packages and Create your package manifest.

A .NET tool is a NuGet package containing a console application. Two project properties, PackAsTool and ToolCommandName, turn a project into one, dotnet pack builds the package and dotnet nuget push publishes it. Users install it globally (dotnet tool install --global), in a custom location (--tool-path) or as a local tool recorded in .config/dotnet-tools.json, which dotnet tool restore reinstalls, pinning the version per repository. The project fragment and the three install forms are on the Swift & .NET page; the Microsoft documentation warns that tools run in full trust and that the manifest decides what dotnet tool run executes, so keep it under review.

References: .NET tools and Create a .NET tool.

GoReleaser automates the release: it builds the binaries, archives them, writes checksums, signs, and can publish to package managers (Homebrew and winget among them), Docker images and SBOM generation. Its configuration is .goreleaser.yaml; goreleaser init creates one, goreleaser check validates it, goreleaser release --snapshot --clean produces a local trial release without publishing, and goreleaser release performs the real one. It documents Go, Rust, TypeScript, Zig and Python projects, so it also fits a Rust CLI such as the docsctl Rust variant.

Always run the snapshot form in CI on pull requests, so a broken release configuration fails before the tag rather than on it. References: GoReleaser, archives and signing.

A container image gives CI jobs and sandboxes an identical runtime without installing anything on the host. The general practices (minimal, pinned base image, multi-stage builds, a non-root user, no secrets baked in) are documented on the Docker reference, in particular Image Best Practices and Supply-Chain Security; the image for a native docsctl follows them.

The ENTRYPOINT in exec form makes the image behave like the CLI: docker run --rm IMAGE search kalman --json prints JSON on stdout and returns docsctl’s exit code as the container’s. Three habits matter for agents. Do not allocate a terminal (-t) when the output is parsed, because a TTY changes the tool’s behaviour as described in TTY, Colour & Interactivity. Pass credentials by forwarding the variable (-e DOCSCTL_TOKEN with no value copies it from the host environment) or by mounting a token file read-only, and never COPY a credential into an image. And pin the image by digest, not by a tag that can move.

A release should carry evidence of what it is.

The full verification recipe with cosign verify-blob, the identity and issuer to accept, and the caveat that an attestation links an artifact to its source and build rather than certifying it as safe, is in the "Signed releases" section of Security. References: Sigstore — Signing blobs and GitHub — Use artifact attestations.