Guides
Shell completion
On this page
The Homebrew cask installs completion for bash, zsh and fish. For any other install method, install it yourself.
Install #
brig completion bash|zsh|fish prints a completion script to stdout. Brig does not install the script and does not write to your startup files. The location of the script depends on the shell and the host.
brig completion bash > /usr/local/etc/bash_completion.d/brigWithout a completion directory:
echo 'eval "$(brig completion bash)"' >> ~/.bashrcThe file must be called _brig, and it must be on your fpath.
brig completion zsh > "${fpath[1]}/_brig"Then start a new shell, or run:
compinitbrig completion fish > ~/.config/fish/completions/brig.fishThe script asks the brig on your PATH what to offer, so a new verb or flag needs no reinstall. Reinstall the script only when the script changes.
Completion by position #
| Where the cursor is | What is offered |
|---|---|
| Before the verb | The verbs, and the three global flags (--verbose, -q/--quiet, --json) |
| A flag, either side of the ref | The run-line flags that verb accepts. Brig reads those on both sides. |
| A ref | Every agent, and every session under one: claude, claude@refactor |
brig run <ref> … |
The project directory, for the first word only |
| Once the agent's arguments have begun | Nothing |
Flags #
Completion offers a flag by its position on the line, whether or not the verb uses the value. Brig reads brig run claude --mem 4096. --mem therefore completes before and after the ref, on every verb that reads run-line flags.
The global flags complete only before the verb. Completion does not offer --verbose or -q/--quiet beside the ref:
| Flag | Why it is not offered beside the ref |
|---|---|
--verbose |
It has no run-line form. |
-q/--quiet |
Its run-line form is the retiring spelling, and completion never offers a retiring spelling. |
Two flags complete their values:
| Flag | Values offered |
|---|---|
--network |
Its three postures |
--home |
Directories |
After the first word or flag that Brig does not own, completion offers nothing.
Refs #
| Verbs | Refs offered | Reason |
|---|---|---|
run, sh, info |
Every agent | These verbs take an agent that has never run. |
stop, rm |
The sessions that exist | These verbs act on a sandbox that exists. |
brig rm --all |
None | The line names no session. It offers only --dry-run and --yes. |
Noun commands #
Under the noun commands (agent, policy, secret, telemetry), the subcommands complete. So do the names they take:
| Command | Names offered |
|---|---|
agent show |
Agents |
agent edit, agent rm |
The agents with a file of their own |
policy attach |
Policies |
Omitted completions #
Completion does not offer two things.
Secret names. Listing them opens your keyring. On macOS that means security dump-keychain. On Linux, a secret-service backend can raise an unlock prompt. Use brig secret ls to list them.
Retired spellings. Each one still works and prints one line that names its replacement. See Migration for the full old-to-new list.
Stale session names #
Completion reads session labels from Brig's session index, which is a file. It does not ask the runtime.
A sandbox removed outside Brig (with nerdctl rm, for example) stays on offer until the next brig ls prunes it. A command that uses the stale name reports that the sandbox is gone.