Alias Commands

Create your own shortcuts for bb commands, mirroring gh alias. An alias expands in place of the first argument: after bb alias set co 'pr checkout $1', running bb co 42 runs bb pr checkout 42.

Aliases are stored in the aliases map of the configuration file and are managed with the commands below (not with bb config set).

How expansion works

• The first argument after bb is looked up in your alias map. Built-in command names always win: an alias can never shadow a real bb command.
• $1–$9 placeholders in the expansion are filled from the arguments that follow the alias. Missing arguments are an error.
• Arguments not consumed by a placeholder are appended to the expanded command.
• Expansion runs once. An alias cannot reference another alias.

bb alias set

Create or update an alias.

bb alias set <name> <expansion>

Examples

# Shortcut with a placeholder (single quotes keep $1 literal for bb)
bb alias set co 'pr checkout $1'
bb co 42                      # → bb pr checkout 42

# Shortcut for a flag-heavy invocation
bb alias set prd "pr create --draft"
bb prd -t "My PR"             # → bb pr create --draft -t "My PR"

# JSON output
bb alias set co 'pr checkout $1' --json

Shell passthrough (! prefix)

An expansion starting with ! is run through sh -c (PowerShell on Windows without sh, see below) instead of being parsed as a bb command. The arguments after the alias are available as shell positional parameters ($1, $@), so pipes, xargs, and other shell constructs work:

bb alias set igrep '!bb pipeline list --all --json | grep "$1"'
bb igrep deploy               # → sh -c 'bb pipeline list --all --json | grep "$1"' bb-alias deploy

On Windows

Windows usually has no sh on PATH (Git for Windows only adds it inside Git Bash). When sh isn’t found, bb runs the body as a PowerShell script block instead, with pwsh if it’s installed and Windows PowerShell otherwise. The arguments arrive in $args ($args[0] is the first), and the alias exits non-zero when its last command fails, with a native command’s own exit code. Write the body in PowerShell syntax:

bb alias set igrep '!bb pipeline list --all --json | Select-String $args[0]'
bb igrep deploy

Where sh is on PATH (Git Bash, MSYS2, Cygwin, WSL) the alias still runs through sh -c, so existing POSIX aliases keep working there. The choice follows PATH, not the terminal you typed in, so the same alias can run in sh from Git Bash and in PowerShell from a PowerShell window. Write the body for the shell you run bb from.

Caution

Shell aliases execute arbitrary shell commands you define. They run with your permissions, exactly like a shell function or an entry in your shell rc file; only define shell aliases you understand. Where supported, config files use 0600 permissions to restrict access to the file owner.

bb alias list

List configured aliases.

bb alias list

Examples

bb alias list
bb alias list --json

bb alias delete

Delete an alias.

bb alias delete <name>

Examples

bb alias delete co
bb alias delete co --json