b install
Install binaries and sync environment files. If no arguments are given, b installs all binaries and syncs all envs from the b.yaml configuration file. You can also install specific binaries or env files on-the-fly.
Alias
i
Usage
Examples
Install all from config
If a b.yaml file is present, this command will install all binaries and sync all env files listed in it.
When an env of b.yaml fails, or b refuses its key, b install shows a ✗ line for that env. It syncs the other envs and installs the binaries. Then it stops with an error that gives the number of envs that failed and names each one as its ✗ line does (exit code 1), as b update does. This is also true for b install <key> with the key of an env of b.yaml. When a download also fails, the error names both.
Install a specific binary
Install the latest version of a specific binary.
Install a specific version
Append @<version> to the binary name to install a specific version.
Install any GitHub release
Use a full provider reference to install any binary from GitHub releases.
Install and add to config
Use the --add flag to install a binary and simultaneously add it to your b.yaml.
With --add, --on-post and --asset go into the b.yaml entry of the binary, also into an entry that is already there. An enforced pin holds only the version, so they also go into a pinned entry.
When a download fails, b install --add does not change b.yaml, also when other binaries of the same command install. The command stops with an error that names each binary whose download failed. Run it again when the download works.
Force an installation
Use the --force flag to overwrite an existing binary.
Install with an alias
Use the --alias flag to install a binary under a different name. This is useful when you want to use a custom name for a binary while still using the original binary's implementation.
This installs renvsubst but makes it available as envsubst. The alias binary will:
- Download and install the original binary (
renvsubst) - Create the alias binary file (
envsubst) - Work with all commands like version detection and execution
- Show in listings with the alias relationship:
renvsubst (envsubst)
You can combine --alias with other flags:
Rules for --alias:
- It takes one binary argument. To give several binaries an alias, install each one on its own.
- When the alias is the name of a b.yaml entry of the same binary, the install uses the settings of that entry (version, enforced pin, file, onPost). A version on the command line wins.
- When the alias is a new name, the binary keeps the settings of the b.yaml entry of the binary argument: its version (its enforced pin, when it has one) and its onPost. It does not keep that entry's file: it installs at
.bin/<alias>. A version on the command line and--on-postwin. With--add, the new entry gets that version and onPost, without a pin. - When the alias is already the name of another binary, b refuses the install. That is another entry in b.yaml, the binary of a provider ref, or another preset (a built-in binary of that name), also when that preset has no entry in b.yaml.
- For another preset without an entry,
--forceinstalls the binary under the alias anyway, and overwrites the file of that preset. The b.lock row of that file then names the binary that is in it, so a laterb install <preset>downloads the preset again. For an entry of another binary,--forcedoes not help: b.yaml would then give one name to two binaries.
With --add, b does not write a version that the entry's enforced pin contradicts. Add --fix to move the pin as well. A version that is the pin without or with a leading v (3.0.0 for a pin v3.0.0) is the pinned version: b installs it and writes it as the pin spells it.
The b.lock rows of binaries
b install writes one row into b.lock for each file that it installs. The name of the row is the name of the file in .bin: the alias of the binary when it has one, else the name of the binary. A file that b.yaml puts in another directory with file: has a row under that file: as b.yaml writes it, cleaned. A relative path gets ./ or ../ in front and is relative to the directory of b.yaml, where b.lock is: for example ../tools/x. An absolute path, such as /usr/local/bin/custom-tool, stays absolute. b does not resolve the symlinks in these names. So the name of a row is the same in each checkout of the project with the same layout, also through a symlink, and b.lock holds no path that b.yaml does not hold. When b writes b.yaml (for example b install --add), a relative file: stays as you wrote it. So two b.yaml entries of one preset, or two provider refs with the same binary name under their own aliases or file: paths, each have their own row. b verify checks the file at the path of the row.
All providers write the binary to this file: the release providers (GitHub, GitLab, Gitea) and go://, git://, docker:// and oci://. The name of the binary only tells b which file to take from the source. For go://, the binary name is the name that go install gives the binary: the last element of the package path. A major version suffix does not count, so go://example.com/tool/v2 installs tool.
Older versions of b wrote the binary of a go://, git://, docker:// or oci:// entry with an alias or a file: under the binary name, in the directory of the file. For example, alias: ta gave .bin/tool, not .bin/ta. After an upgrade, b installs the binary to the file that b.yaml names. On Windows, this file has no .exe suffix, unless file: or the alias names one. The old file stays. When no entry names the old file, remove it. The next b install then removes its b.lock row.
When the file has another name than its binary, the row names the binary in the field binary. When a row says that the file is another binary (another binary, a provider ref for a preset, a preset or another ref for a provider ref, or for a row without binary the repository of another preset), b install downloads the binary again, also when no version is asked for. An older b drops the field binary when it writes b.lock again; for a preset without a GitHub repository, b then cannot tell the binary of the file.
Older versions of b wrote some rows under another name: the row of a provider ref with an alias and (before alias entries had their own rows) the row of an alias entry of a preset under the name of the binary, and the row of an entry with file: under its alias or the name of its binary. Before they download a binary or remove a row, b install and b update find such a row and write it under the name of the file, when the sha256 of the file is the one in the row. Then b does not download the binary again. A row with another sha256 is the row of another file, and b does not use it. The row under the old name stays while it can describe a file: a b.yaml entry installs a file of that name, or the file is there.
b install and b update without arguments also remove the rows that describe no file: no b.yaml entry installs a file of that name, and the file of the row is not there. A dangling symlink, a symlink loop or a path through a file (plain/sub) is no file. For a row outside the project, b only finds out whether the file is there; it does not read the file. Such a row is the row of an entry that you removed from b.yaml, or a row of an older b under an old name. b verify reports it as missing. A row of a file that is there stays, also without an entry in b.yaml: for example a binary that you installed without --add, or an entry of another configuration file (--config) that uses the same b.lock. An older b wrote the row of a file: entry under a name, not under the path of its file. So after an upgrade of b, run b install once with each configuration file that has file: entries outside .bin: else an install with another configuration file removes such a row, and the binary downloads once more.
Two b.yaml entries must not install the same file. That happens with two provider refs that have the same binary name, with a provider ref whose alias (or binary name) is the name of another entry, or with two entries that have the same file:. b compares the full path of each file, with its symlinks resolved. A relative file: is relative to the directory of b.yaml. For example, with .bin/b.yaml in the project /src/app, file: ../tools/x and file: /src/app/tools/x are the same file. A symlink and the file that it points to are also the same file, also when that file is not there yet. For such a symlink, b reads a .. in its target as text. When a symlink comes before the .. in that target, b can get another file than the system, and then b may not find a duplicate. Names that differ only in case are two files for this check. On a file system that ignores case, b may not find such a duplicate. The two binaries would replace each other at each install. b install and b update refuse such a b.yaml and name the entries and the file. When the entries write the file in two forms, the error gives the full path and each form. b update --envs-only, --group and --plan-json touch no binaries and do not refuse it. b install --add also refuses to add an entry that installs the file of another entry, before it downloads anything. Give a provider ref its own file name with alias: <name> (or --alias <name> with --add), or remove one of the entries.
Sync environment files (SCP syntax)
Use SCP-style syntax to sync files from upstream git repositories:
The SCP syntax is: <repo>[@<version>]:/<glob> [<dest>]
- repo — A git-cloneable reference (e.g.,
github.com/org/repo) - version (optional) — A git tag, branch, or commit to pin
- glob — A file pattern to match in the repository (e.g.,
manifests/**) - dest (optional) — Local directory for the synced files; defaults to the matched path structure
Install from SSH repos
Use SSH URLs for private repositories (requires ssh-agent):
Install from local repos
Install from container images
Use docker:// to pull from a local container runtime, or oci:// to pull
daemonless from any OCI registry (Docker Hub, ghcr.io, quay.io, private).
# docker:// — requires a running docker/podman/nerdctl
b install docker://alpine/helm
b install docker://docker@cli # tag via @ (docker:cli image)
b install docker://docker@cli:/usr/local/bin/docker # explicit in-container path
# oci:// — daemonless; works in CI containers without docker
b install oci://ghcr.io/org/img@v1
b install oci://docker@cli:/usr/local/bin/docker
The syntax is: <docker://|oci://><image>[@<tag>][:/<path-in-image>]
- image — An image reference, including optional registry (e.g.,
alpine,ghcr.io/org/img) - tag (optional, after
@) — Image tag; defaults tolatest. Use@consistently with every otherbprovider rather than docker's nativeimage:tagsyntax - path (optional, after
:/) — Absolute path to the binary inside the image. When omitted,bsearches/usr/local/bin,/usr/bin,/bin, and/appfor a file named after the image's last segment.bwrites the binary to.bin/<name>, or to the alias or thefile:of the b.yaml entry
The leading / on the path disambiguates it from an image:tag pasted from docker documentation. For private registries, oci:// reads credentials from ~/.docker/config.json (same as docker login); see the authentication page.
Post-install hooks
Run a shell command after a binary is installed or updated. The hook only fires
when the on-disk binary actually changed — not on no-op skips or --dry-run.
The hook receives these environment variables:
| Variable | Description | Example |
|---|---|---|
B_EVENT | install or update | install |
B_NAME | Binary name | argsh |
B_VERSION | Version being installed | v0.6.6 |
B_FILE | Absolute path to the binary | /project/.bin/argsh |
In b.yaml:
Hooks are POSIX shell commands (run via sh -c), executed in the project root
directory — so relative paths like .completions/... resolve from there. Non-zero
exit produces a warning but does not fail the install. Output goes to stderr so it
doesn't interfere with progress bars. Hooks are also skipped during b update --dry-run
and --plan-json.
Flags
| Flag | Description |
|---|---|
--add | Add binary/env to b.yaml during install |
--alias | Install binary under a different name |
--fix | Pin the specified version in b.yaml |
--on-post | Shell command to run after install/update (saved with --add) |
-h, --help | help for install |
Global Flags
| Flag | Description |
|---|---|
-c, --config string | Path to configuration file (current: /home/fentas/github/fentas/b/.bin/b.yaml) |
--force | Force operations, overwriting existing binaries |
-q, --quiet | Quiet mode |
-v, --version | Print version information and quit |