brig docs

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/brig

Without a completion directory:

echo 'eval "$(brig completion bash)"' >> ~/.bashrc

The 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:

compinit
brig completion fish > ~/.config/fish/completions/brig.fish

The 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.

Type a command, a flag or an error message.