Skip to content
Bitbucket CLIBitbucket CLI

Completion Commands

Tab completion for bash, zsh, and fish.

Global options: every global flag is accepted here (see Global Flags). Only --json, --no-color and --no-unicode change anything — --jq needs --json, and --no-truncate/--locale/-w/-r have no output to affect.

bb completion install

Section titled “bb completion install”
Terminal window
bb completion install [options]

This command is interactive. It asks two questions:

  1. “Which Shell do you use ?” — pick bash, zsh, or fish. The default is bash; the prompt does not preselect your current shell.
  2. “We will install completion to <file>, is it ok ?” — confirm, or decline and supply an absolute path of your own.

It then appends a source line to that file and writes the completion script under ~/.config/tabtab/.

Shell Config file offered
bash ~/.bashrc
zsh ~/.zshrc
fish ~/.config/fish/config.fish

Because it prompts, bb completion install is not scriptable. It blocks on the shell question in CI, --json included.

A failure throws error code 9001 (COMPLETION_INSTALL_FAILED) with the message Failed to install completions: <error>, and the command exits 1.

After installing

Section titled “After installing”

Restart your shell, or source the file you chose:

Terminal window
source ~/.bashrc                    # bash
source ~/.zshrc                     # zsh
source ~/.config/fish/config.fish   # fish

Then check it works:

Terminal window
bb <Tab>        # every top-level command (the root flags are offered too)
bb repo <Tab>   # clone, create, list, view, delete, default-reviewers

JSON output

Section titled “JSON output”

--json replaces both the success line and the “Restart your shell…” follow-up with a single object:

{
  "success": true,
  "shellCompletion": {
    "command": "bb",
    "installed": true
  }
}

bb completion uninstall

Section titled “bb completion uninstall”
Terminal window
bb completion uninstall [options]

No prompt. It deletes ~/.config/tabtab/bb.<shell>, removes the bb lines from ~/.config/tabtab/__tabtab.<shell>, and drops the source line from your shell config once no other package is left in that file. Both <shell> and that config file come from $SHELL — your login shell, not the shell you happen to be typing in, and not the shell you picked at the install prompt. If they disagree, the source line is left behind and you have to delete it by hand. On success it prints ✓ Shell completions uninstalled successfully!; with --json you get the same envelope as install, with "installed": false.

Most uninstall failures are swallowed by tabtab: it prints ERROR while uninstalling <error> and resolves anyway, so the command still reports success and exits 0. Error code 9002 (COMPLETION_UNINSTALL_FAILED) only fires for failures thrown outside that handler.

What gets completed

Section titled “What gets completed”

Completions are generated from the live command tree, so they always match the commands and flags the CLI actually ships.

  • Commands and subcommands — every command in the tree, at every depth.
  • Options — every flag on the command plus the inherited globals (--json, --jq, --no-color, --no-unicode, --no-truncate, --locale, --workspace, --repo, --help), plus --version on the bare bb. Only long forms are suggested; short aliases like -w still work but are never offered.
  • Flag values for options with a fixed set of choices.

Commands and flags carry their help text as a completion description. zsh and fish display it alongside the name; bash shows bare names. Enum values never carry a description, so they are bare in every shell.

Flag-value completion

Section titled “Flag-value completion”

Completing right after a flag that takes a fixed set of values suggests those values, and nothing else:

Terminal window
$ bb pr merge 42 --strategy <Tab>
merge_commit         squash               fast_forward
squash_fast_forward  rebase_fast_forward  rebase_merge


$ bb pr list --state <Tab>
OPEN  MERGED  DECLINED  SUPERSEDED


$ bb snippet list --role <Tab>
owner  contributor  member


$ bb pr diff --color <Tab>
auto  always  never


$ bb api -X <Tab>
GET   POST     PUT  PATCH
HEAD  OPTIONS  DELETE

Example session

Section titled “Example session”
Terminal window
$ bb pr<Tab>
pr


$ bb pr <Tab>
activity  approve   checks    checkout  comments  create    decline
diff      edit      list      merge     ready     reviewers view


$ bb pr create --<Tab>
# the command's own flags, plus inherited global flags:
--title                 --body          --source       --destination
--close-source-branch   --draft         --reviewer     --default-reviewers
--no-default-reviewers
--json                  --jq            --no-color     --no-unicode
--no-truncate           --locale        --workspace    --repo         --help
Section titled “Related”