bb is the missing command line interface for Bitbucket. It brings the power of the Bitbucket platform to your command line. Creating and merging Pull Requests, cloning repositories, and more are now just a few keystrokes away.

You can grab the latest Debian/Ubuntu package on the Downloads pages.

If you use Homebrew, you can install bb with:

brew install gildas/tap/bitbucket-cli

You can also install bb with snap:

sudo snap install bitbucket-cli
sudo snap alias bitbucket-cli bb

You can get bb from Homebrew with:

brew install gildas/tap/bitbucket-cli

You can get bb from Chocolatey with:

choco install bitbucket-cli

You can also install bb with scoop:

scoop bucket add gildas https://github.com/gildas/scoop-bucket
scoop install bitbucket-cli

You can download the latest version of bb from the downloads page.

Once you get the bb executable, you can install/copy it anywhere in your $PATH.

bb is a modern command line interface. It uses subcommands to perform actions. You can get help on any subcommand by running bb <subcommand> --help.

General help is also available by running bb --help or bb help.

By default bb works in the current git repository. You can specify a Bitbucket repository with the --repository flag.

Many commands and flags are dynamically auto-completed. See the Completion section for more information about completion.

Most delete, upload, and download commands support multiple arguments. You can pass a list of arguments or a file with one argument per line:

bb repo delete myrepository1 myrepository2 myrepository3

You can tell bb to stop on the first error, warn on errors, or ignore errors when processing multiple arguments with the --stop-on-error, --warn-on-error, or --ignore-errors flags.

All commands that would modify something on Bitbucket now allow you to preview the changes before applying them. You can use the --dry-run flag to see what would happen.

bb repo delete myrepository3 --dry-run

get and list commands support the --columns flag to specify which columns to display in the output. You can pass a comma-separated list of columns, repeat the flag, or use all to display all columns. If you do not provide this flag, the default columns are displayed.

bb repo list --columns all
bb repo list --columns name,slug,project
bb repo list --columns name --columns slug

list commands also support the --sort flag to sort the output by a specific column. You can pass a comma-separated list of columns, repeat the flag, or use all to sort by all columns. If you do not provide this flag, the default sorting is used.

bb repo list --sort name

bb outputs a table by default. You can change the output format with the --output flag, by setting the BB_OUTPUT_FORMAT environment variable, or by modifying the profile configuration (See Profiles).

The following formats are supported:

• csv: CSV
• json: JSON
• yaml: YAML
• tsv: TSV
• table: Table

For example:

bb --output json workspace list

Or

bb workspace list --output json

Changing the format with the environment variable BB_OUTPUT_FORMAT can be done like this:

export BB_OUTPUT_FORMAT=json
bb workspace list

The Table output format displays the data in a human-readable format. Here is an example of the output for the bb pullrequest list command:

$ bb pr list --state all
+----+---------------------------+--------------------------------+---------------------+-------------+----------+
| ID |           TITLE           |          DESCRIPTION           |       SOURCE        | DESTINATION |  STATE   |
+----+---------------------------+--------------------------------+---------------------+-------------+----------+
|  1 | Merge feature/links       | Feature links. Do not delete   | feature/links       | dev         | DECLINED |
|    |                           | the feature branch after the   |                     |             |          |
|    |                           | merge.                         |                     |             |          |
|  2 | Merge feature/links       | Feature links. Do not delete   | feature/links       | dev         | MERGED   |
|    |                           | the feature branch after the   |                     |             |          |
|    |                           | merge.                         |                     |             |          |
|  3 | Merge release/1.0.0       | Feature 1.0.0. Do not delete   | release/1.0.0       | master      | MERGED   |
|    |                           | the feature branch after the   |                     |             |          |
|    |                           | merge.                         |                     |             |          |
|  4 | Merge feature/bb          | Feature bb. Do not delete the  | feature/bb          | dev         | DECLINED |
|    |                           | feature branch after the merge |                     |             |          |
|  5 | Merge feature/bb          | Feature bb. Do not delete the  | feature/bb          | dev         | MERGED   |
|    |                           | feature branch after the merge |                     |             |          |
|  6 | Merge feature/bb-doc      | Feature bb-doc. Do not delete  | feature/bb-doc      | dev         | MERGED   |
|    |                           | the feature branch after the   |                     |             |          |
|    |                           | merge.                         |                     |             |          |
+----+---------------------------+--------------------------------+---------------------+-------------+----------+

bb uses profiles to store your Bitbucket credentials. You can create a profile with the bb profile create command:

bb profile create \
  --name myprofile \
  --client-id <your-client-id> \
  --client-secret <your-client-secret> \
  --callback-port 8080

You can also pass the --default flag to make this profile the default one, or pass a --output flag to change the profile output format.

You can also pass the --default-workspace and/or --default-project flags to set the default workspace and/or project for this profile.

You can also pass the --progress flag to display a progress bar when upload/downloading artifacts and attachments.

By default, the password or client secret is stored in the vault of the operating system (Windows Credential Manager, macOS Keychain, or Linux Secret Service). You can pass the --no-vault flag to disable this feature and store the password or client secret in plain text in the configuration file. This is not recommended, but can be useful for testing purposes.

Profiles support the following authentications:

• OAuth 2.0 with Authorization Code Grant with the --client-id, --client-secret, and --callback-port flags
• OAuth 2.0 with Client Credentials with the --client-id and --client-secret flags
• App passwords with the --user and --password flags.
• Repository Access Tokens, Project Access Tokens, Workspace Access Tokens with the --access-token flags.

When you use a username/password, the password is stored in the vault of the operating system (Windows Credential Manager, macOS Keychain, or Linux Secret Service). You can pass the --no-vault flag to disable this feature and store the password in plain text in the configuration file. This is not recommended, but can be useful for testing purposes. On Linux and macOS, you can also pass the --vault-key flag to set the key to use in the system keychain. By default, the key is bitbucket-cli. On Windows, this option is not available.

You can also pass the --clone-protocol flag to set the default protocol to use when cloning repositories. The supported protocols are https, git, and ssh. This option can be overridden with the --protocol flag when using repo clone.

In case you are not using a user/password, you can also pass a --clone-user flag to set the username to use when cloning repositories with the https protocol. If you use a user/password, you don't need to set this flag, usually, ans the username will be used for cloning repositories. This option can be overridden with the --user flag when using repo clone.

You can get the list of your profiles with the bb profile list command:

bb profile list

You can get the details of a profile with the bb profile get or bb profile show command:

bb profile get myprofile

You can ge the details of the current profile:

bb profile get --current

Or:

bb profile which

You can update a profile with the bb profile update command:

bb profile update myprofile \
  --client-id <your-client-id> \
  --client-secret <your-client-secret>

You can delete a profile with the bb profile delete command:

bb profile delete myprofile

You can set the default profile with the bb profile use command:

bb profile use myprofile

You can also set the profile with the environment variable BB_PROFILE:

export BB_PROFILE=myprofile

The profile can also come from your current .git/config file. You can set the bb.profile variable in the [bitbucket "cli"] section of your .git/config file:

[bitbucket "cli"]
  profile = myprofile

git config --local bitbucket.cli.profile myprofile

The current profile comes in order from:

• the --profile flag
• the BB_PROFILE environment variable
• the profile variable in the [bitbucket "cli"] section of your .git/config file,
  if the profile does not exist, the command will print a warning and use the default profile
• the profile marked default in the configuration file
• the first profile in the configuration file

Profiles are stored in the configuration file. By default, the configuration file is located:

• on Linux: $XDG_CONFIG_HOME/bitbucket/config-cli.json, or ~/.config/bitbucket/config-cli.json, then ~/.bitbucket-cli
• on macOS: $HOME/Library/Application Support/bitbucket/config-cli.json, then ~/.bitbucket-cli
• on Windows: %AppData%\bitbucket\config-cli.json, then $HOME/.bitbucket-cli
• on Plan 9: $home/lib/bitbucket/config-cli.json, then ~/.bitbucket-cli

You can also override the location of the configuration file with the environment variable BB_CONFIG or the --config flag:

export BB_CONFIG=~/.bb/config.json

bb --config ~/.bb/config.json workspace list

To add an OAuth 2.0 profile, you need to create an OAuth consumer on Bitbucket. First, go to the settings page https://bitbucket.org/xxxx/workspace/settings of the Bitbucket workspace you want a consumer for (where xxxx is the workspace name/ID). On that page, click on the OAuth consumers link in the Access management section. Then click on the Add consumer button. Fill in the form.

To use an OAuth 2.0 with Authorization Code Grant, you will need to fill in the Callback URL with a link like http://localhost:yyyy (where yyyy is the port you want to use and provide to the --callback-port flag of bb profile create) and do not enable the check box for This is a private consumer.

To use an OAuth 2.0 with Client Credentials, you will need to enable the check box for This is a private consumer and do not fill in the Callback URL.

In both cases, you will need to fill in the permissions you want to grant to the consumer.

Once you hit the Save button, your OAuth consumer will be created and you can use the credentials (client identifier and secret) provided to configure your profile with bb.

Once the profile is created in bb, for an OAuth 2.0 with Authorization Code Grant, you will need to authorize the profile with the following command:

bb profile authorize myprofile

You can also use the --verbose to get some information about the authorization process.

You can list workspaces with the bb workspace list command:

bb workspace list

With the --membership flag, you can see the kind of membership you have in each workspace:

bb workspace list --membership

You can also get the details of a workspace with the bb workspace get or bb workspace show command:

bb workspace get myworkspace

Additionally, you can get the members of a workspace with the flag --members:

bb workspace get myworkspace --members

Or, even, a specific member with the flag --member:

bb workspace get myworkspace --member mymember

You can list projects with the bb project list command. If the --workspace flag is not provided, the default workspace of the profile is used (if the profile does not have a default workspace, the command will fail):

bb project list --workspace myworkspace

The --workspace flag is also dynamically auto-completed with the workspaces you have access to.

You can also get the details of a project with the bb project get or bb project show command:

bb project get myproject --workspace myworkspace

You can create a project with the bb project create command:

bb project create \
  --name myproject \
  --key MYPROJECT

You can update a project with the bb project update command:

bb project update myproject \
  --name myproject

You can delete a project with the bb project delete command:

bb project delete myproject

You can list the default reviewers of a project with the bb project reviewer list command. In addition to the --workspace, if the --project flag is not provided, the default project of the workspace is used (if the workspace does not have a default project, the command will fail):

bb project reviewer list --workspace myworkspace --project myproject

You can add a default reviewer to a project with the bb project reviewer add command:

bb project reviewer add userUUID

The {} around the userUUID are optional.

You can remove a default reviewer from a project with the bb project reviewer remove command:

bb project reviewer remove userUUID

You can get the details of a default reviewer with the bb project reviewer get or bb project reviewer show command:

bb project reviewer get \
  --workspace myworkspace \
  --project myproject \
  userUUID

You can list repositories with the bb repo list command:

bb repo list --workspace myworkspace

If you do not provide a workspace, the command will attempt to list all repositories you have access to, which can take a very long time.

You can narrow down the list of repositories with the --role, --project, --project-key, --has-issues, --has-wiki, --is-private, --language, and --main-branch flags:

bb repo list --workspace myworkspace \
  --role        owner \
  --project     myproject \
  --has-issues  true \
  --has-wiki    true \
  --is-private  false \
  --language    go \
  --main-branch master

All filterers are optional and combined with an AND operator.

You can also get the details of a repository with the bb repo get or bb repo show command. If the --workspace flag is not provided, the default workspace of the profile is used (if the profile does not have a default workspace, the command will fail):

bb repo get --workspace myworkspace myrepository

You can clone a repository with the bb repo clone command:

bb repo clone myworkspace/myrepository

You can set the protocol to use when cloning a repository with the --protocol flag. The supported protocols are https, git, and ssh. If not provided, the protocol set in the profile is used (if the profile does not have a protocol set, the default is git).

When using the ssh protocol, you can specify the SSH key to use with the --ssh-key-file flag. If not provided, the key set in the profile is used (if the profile does not have a key set, the default is ~/.ssh/id_rsa).

When using the https protocol while cloning a private repository, you can specify the username to use for authentication with the --user flag. If the username is not provided, the cloneUser from the profile is used. If the profile does not have a cloneUser, you cannot clone a private repository with the https protocol.

or, with the --workspace flag:

bb repo clone --workspace myworkspace myrepository

Or, using the profile's default workspace:

bb repo clone myrepository

By default, the repository is cloned in a folder with the same name as the repository. You can specify a different folder with the --destination flag:

bb repo clone --workspace myworkspace --destination myfolder myrepository

By default, the repository is cloned using the git protocol. You can change the protocol with the --clone-protocol flag. The supported protocols are https, git, and ssh. The default protocol can also be set in the profile with the --clone-protocol flag when creating or updating a profile.

bb repo clone --clone-protocol https myrepository

When using the ssh protocol, you can also specify the SSH key to use with the --ssh-key flag (by default the key configured is SSH for bitbucket.org is used, and if nothing is configured: ~/.ssh/id_rsa):

bb repo clone --ssh-key /path/to/ssh/key myrepository

When using the https protocol while cloning a private repository, you can specify the username to use for authentication with the --username flag. If the username is not provided, the cloneVaultUsername from the profile is used. If the profile does not have a cloneVaultUsername, you cannot clone a private repository with the https protocol.

On Linux and macOS, the system keychain will be used to retrieve the credentials. You can set the cloneVaultKey in the profile to use a specific key in the keychain. If not set, the default value is bitbucket-cli-clone. You can also set the cloneVaultUsername in the profile to use a specific username for authentication.
On Windows, the Windows Credential Manager will be used to retrieve the credentials. And the username should be <cloneVaultKey>:<cloneVaultUsername>.

bb repo clone --username myusername myrepository

You can create a repository with the bb repo create command:

bb repo create myrepository_slug \
  --name      myrepository \
  --project   myproject \
  --workspace myworkspace

If the --project flag is not provided, the repository will be created in the default project of the profile.

You can update a repository with the bb repo update command:

bb repo update --workspace myworkspace myrepository \
  --private \
  --fork-policy no_public_forks

You can delete a repository with the bb repo delete command:

bb repo delete --workspace myworkspace myrepository

You can fork a repository with the bb repo fork command:

bb repo fork myrepository \
  --workspace myworkspace \
  --project   myproject \
  --name      myfork

You can list the forks of a repository with the bb repo get --forks command:

bb repo get myrepository \
  --workspace myworkspace \
  --forks

You can list pull requests with the bb pullrequest list command:

bb pullrequest list

You can create a pull request with the bb pullrequest create command:

bb pullrequest create \
  --title "My pull request" \
  --source "my-branch" \
  --destination "master"

You can add reviewers to the pull request with the --reviewer flag:

bb pullrequest create \
  --title "My pull request" \
  --source "my-branch" \
  --destination "master" \
  --reviewer    username1 --reviewer {userUUID2}

If the first reviewer is default, the command will try to get the default reviewers from the project settings.

You can get the details of a pull request with the bb pullrequest get or bb pullrequest show command:

bb pullrequest get 1

You can approveor unapprove a pull request with the bb pullrequest approve or bb pullrequest unapprove command:

bb pullrequest approve 1

You can decline a pull request with the bb pullrequest decline command:

bb pullrequest decline 1

You can merge a pull request with the bb pullrequest merge command:

bb pullrequest merge 1

If no pull request is provided, the command will try to merge the pull request with the current branch.

You can list the comments of a pull request with the bb pullrequest comment list command:

bb pullrequest comment list --pullrequest 1

You can add a comment to a pull request with the bb pullrequest comment create or bb pullrequest comment add command:

bb pullrequest comment add --pullrequest 1 \
  --comment "My comment" \
  --file    README.md \
  --line    404

You can resolve a comment with the bb pullrequest comment resolve command:

bb pullrequest comment resolve --pullrequest 1 452466

You can re-open a comment with the bb pullrequest comment reopen command:

bb pullrequest comment reopen --pullrequest 1 452466

You can get the details of a comment with the bb pullrequest comment get or bb pullrequest comment show command:

bb pullrequest comment get --pullrequest 1 452466

You can update a comment with the bb pullrequest comment update command:

bb pullrequest comment update --pullrequest 1 452466 \
  --comment "My comment"

You can delete a comment with the bb pullrequest comment delete command:

bb pullrequest comment delete --pullrequest 1 452466

You can list issues with the bb issue list command:

bb issue list

By default, all open and new issues are listed. You can use the --state flag to filter the issues by state:

bb issue list --state open

The flag --state can be used multiple times to filter by multiple states:

bb issue list --state open --state new --state resolved,wontfix

You can create an issue with the bb issue create command:

bb issue create \
  --title "My issue" \
  --content "My issue content"

You can get the details of an issue with the bb issue get or bb issue show command:

bb issue get 1

You can update an issue with the bb issue update command:

bb issue update 1 \
  --title "My issue" \
  --content "My issue content"

You can delete an issue with the bb issue delete command:

bb issue delete 1

You can vote for an issue with the bb issue vote command:

bb issue vote 1

You can unvote for an issue with the bb issue unvote command:

bb issue unvote 1

You can watch an issue with the bb issue watch command:

bb issue watch 1

You can unwatch an issue with the bb issue unwatch command:

bb issue unwatch 1

You can add a comment to an issue with the bb issue comment create or bb issue comment add command:

bb issue comment add --issue 1 \
  --content "My comment"

You can get the details of a comment with the bb issue comment get or bb issue comment show command:

bb issue comment get --issue 1 7643545

You can update a comment with the bb issue comment update command:

bb issue comment update --issue 1 7643545 \
  --content "My comment"

You can delete a comment with the bb issue comment delete command:

bb issue comment delete --issue 1 7643545

You can list the attachments of an issue with the bb issue attachment list command:

bb issue attachment list --issue 1

You can upload an attachment to an issue with the bb issue attachment upload command:

bb issue attachment upload --issue 1 myattachment.zip

You can download an attachment with the bb issue attachment download command:

bb issue attachment download --issue 1 myattachment.zip

You can delete an attachment with the bb issue attachment delete command:

bb issue attachment delete --issue 1 myattachment.zip

You can list artifacts with the bb artifact list command:

bb artifact list

By default the current repository is used, you can specify a repository with the --repository flag.

You can also upload an artifact with the bb artifact upload command:

bb artifact upload myartifact.zip

At the moment, only one file at a time is supported (no folders or stdin). The artifact name is the file name.

You can download an artifact with the bb artifact download command:

bb artifact download myartifact.zip

You can provide a --destination flag to specify the destination folder. If the folder does not exist, it will be created.

You can also pass the --progress flag to display a progress bar when upload/downloading artifacts. This override the default value set at the Profile level.

Finally, you can delete an artifact with the bb artifact delete command:

bb artifact delete myartifact.zip

You can list GPG keys with the bb key list command:

bb gpg-key list

By default, the keys are listed for the current user. You can specify a user with the --user flag.

You can also get the details of a GPG key with the bb key get or bb key show command:

bb gpg-key get <fingerprint>

By default, the key is retrieved for the current user. You can specify a user with the --user flag.

You can create a GPG key with the bb gpg-key create command:

bb gpg-key create \
  --user <user> \
  --name <keyname> \
  --key <key>

The key name is optional. You can also provide the key in a file with the --key-file flag. If the filename is -, the key is read from stdin. If the --user flag is not provided, the key is created for the user associated with the current profile.

You can delete one or more GPG keys with the bb gpg-key delete command:

bb gpg-key delete <fingerprint>

You can list SSH keys with the bb key list command:

bb ssh-key list

By default, the keys are listed for the current user. You can specify a user with the --user flag.

You can also get the details of an SSH key with the bb ssh-key get or bb ssh-key show command:

bb ssh-key get <fingerprint>

By default, the key is retrieved for the current user. You can specify a user with the --user flag.

You can create an SSH key with the bb ssh-key create command:

bb ssh-key create \
  --user <user> \
  --name <keyname> \
  --key <key>

The key name is optional. You can also provide the key in a file with the --key-file flag. If the filename is -, the key is read from stdin. If the --user flag is not provided, the key is created for the user associated with the current profile.

You can delete one or more SSH keys with the bb ssh-key delete command:

bb ssh-key delete <fingerprint>

The bitbucket-cli caches some data to speed up the commands. The following items are cached:

• workspaces
• projects
• users

The cache is stored in the os.UserCacheDir directory, under bitbucket. The values are stored for a duration of 5 minutes, you can override this value with the environment variable BITBUCKET_CLI_CACHE_DURATION (for the format please follow core.ParseDuration). By default, the items are stored as JSON files unencrypted. To encrypt these files, you can set the environment variable BITBUCKET_CLI_CACHE_ENCRYPTIONKEY with an AES-256 key. The key must follow the crypto/aes requirements.

You can clear the cache with the bb cache clear command:

bb cache clear

bb supports completion for Bash, fish, Powershell, and zsh.

To enable completion, run the following command:

source <(bb completion bash)

You can also add this line to your ~/.bashrc file to enable completion for every new shell.

bb completion bash > ~/.bashrc

To enable completion, run the following command:

bb completion fish | source

You can also add this line to your ~/.config/fish/config.fish file to enable completion for every new shell.

bb completion fish > ~/.config/fish/completions/bb.fish

To enable completion, run the following command:

bb completion powershell | Out-String | Invoke-Expression

You can also add the output of the above command to your $PROFILE file to enable completion for every new shell.

To enable completion, run the following command:

source <(bb completion zsh)

You can also add this line to your functions folder to enable completion for every new shell.

bb completion zsh > "~/${fpath[1]}/_bb"

On macOS, you can add the completion to the brew functions:

bb completion zsh > "$(brew --prefix)/share/zsh/site-functions/_bb"

We will add more commands in the future. If you have any suggestions, please open an issue.