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.
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> … or brig plan <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 before the verb. Two of them also complete after it:
| Flag | Where it completes |
|---|---|
--verbose |
Before the verb |
-q/--quiet |
Before the verb, and after ls, which has its own -q |
--json |
Before the verb, and after every verb that accepts it except ls, agent ls and secret ls |
v0.5.0 removed -q after any other verb, so completion does not offer it there.
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, plan |
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 -y/--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 Linux that can raise an unlock prompt. Use brig secret ls to list them.
Retired spellings. Completion offers only the current spelling. The one retired verb left, brig exec, still works and prints a notice that names its replacement. Brig refuses the spellings that v0.5.0 removed. 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 stays on offer until the next brig ls prunes it or brig rm <ref> forgets it. A command that uses the stale name reports that the sandbox is gone.