Managed binaries

Third-party executables are declared, not committed. loadout fetches them per platform into a directory it owns and appends that directory to your PATH.

binaries:
  - name: duckdb
    version: v1.1.3
    source:
      github: duckdb/duckdb
      asset:
        linux-amd64: duckdb_cli-linux-amd64.zip
        darwin-arm64: duckdb_cli-osx-universal.zip
    checksum:
      linux-amd64: sha256:efd0fcc...
      darwin-arm64: sha256:9a1b2c3...

loadout bin list                 # installed, versions, source URLs, verified or not
loadout bin install              # fetch, verify, install everything declared
loadout bin install duckdb       # just one
loadout bin install --force      # reinstall even when current
loadout bin remove duckdb

Why declare rather than commit

A committed linux-amd64 binary is dead weight on a Mac, and a repository that carries several of them gets large quickly — this design replaced 61MB of committed executables with a few lines of YAML.

Declaring also makes version drift visible. A committed binary does not announce that it is two years old. A declared one has a version in the configuration, right where you will see it.

Sources

GitHub releases, resolved by repository and asset name per platform:

source:
  github: duckdb/duckdb
  asset:
    linux-amd64: duckdb_cli-linux-amd64.zip

Direct URLs, when the project does not publish through GitHub:

source:
  url:
    linux-amd64: https://example.com/tool-linux-amd64.tar.gz
    darwin-arm64: https://example.com/tool-darwin-arm64.zip

Platform keys are <os>-<arch>: linux-amd64, linux-arm64, darwin-amd64, darwin-arm64. A binary declaring no asset for the current platform is skipped, and doctor says so.

Checksums

Either one hash for every platform:

checksum: sha256:abc...

or one per platform, which is what you want whenever more than one is declared, because a hash only ever describes a single artefact:

checksum:
  linux-amd64: sha256:abc...
  darwin-arm64: sha256:def...

A binary with no checksum still installs. loadout bin list then says plainly that it was downloaded but not verified, so the gap is visible rather than assumed.

What happens on install

This is the one feature that downloads code and then puts it on your PATH, so the handling is deliberate:

• HTTPS on every redirect hop. Checking only the configured URL is not enough, because release hosts redirect to a CDN and a redirect to http:// would otherwise be followed.
• The checksum is verified before anything is installed, not after.
• Archive members with absolute or .. paths are refused, and extraction is size-capped, so an archive cannot write outside the target directory.
• Writes land via rename, so an interrupted install cannot leave a half-written executable on your PATH.
• Provenance is recorded. bin list shows the exact URL each binary came from, so you can always answer where something on your PATH originated.

PATH ordering

The managed directory is ~/.local/share/loadout/bin, and it is appended to PATH, not prepended.

That means a managed binary cannot silently shadow a system tool. If you install jq through loadout on a machine that already has jq, the system one still wins. This is the safe default; the alternative surprises you on exactly the machines where it matters.

Relationship to scripts

Binaries and scripts both end up on PATH and are managed by the same loadout bin commands, but they are different things: a binary is a downloaded release artefact, a script is text you or loadout authored. Scripts are symlinked rather than fetched, and need no checksum.