Bitbucket CLI is a command-line interface designed to interact with Bitbucket, enabling users to perform tasks such as creating and merging pull requests, cloning repositories, and managing projects directly from the terminal.
Key Features:
Subcommand Structure: Utilizes subcommands for specific actions, allowing users to execute commands like bb pr create or bb repo clone.
Auto-Completion: Supports dynamic auto-completion for commands, flags, and arguments, enhancing efficiency.
Dry-Run Option: Allows previewing changes before execution with the --dry-run flag.
Output Formats: Offers multiple output formats (CSV, JSON, YAML, TSV, Table) to suit different needs.
Profile Management: Enables configuration of profiles for Bitbucket credentials and preferences, supporting OAuth 2.0, app passwords, and access tokens.
Audience & Benefit:
Ideal for developers, DevOps engineers, and teams using Bitbucket, Bitbucket CLI streamlines workflows by providing a flexible and powerful command-line tool for interacting with Bitbucket resources.
README
Bitbucket Command Line Interface
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.
Installation
Linux
You can grab the latest Debian/Ubuntu package on the Downloads pages.
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
list commands also support the --query flag to filter the output by a specific query. The query syntax is similar to the one used in the Bitbucket web interface. For example, to filter Pull Requests updated after a specific date:
bb pullrequest list --query 'updated_on > 2025-12-31'
Please refer to the Bitbucket API documentation for more information about the supported query syntax and fields.
list commands also support the 'page-length' flag to set the number of items to retrieve per request to Bitbucket API at a time. By default, the page length is set on the profile and the default is 50. You can set it to a value between 1 and 100.
bb repo list --page-length 25
Output
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. | | | |
+----+---------------------------+--------------------------------+---------------------+-------------+----------+
Profiles
bb uses profiles to store your Bitbucket credentials. You can create a profile with the bb profile create command:
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.
When you use a user/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:
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:
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
Adding an OAUTH 2.0 Profile
To add an OAuth 2.0 profile, you need to create an OAuth consumer on Bitbucket. First, go to the settings page 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 (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 add a dummyCallback 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.
You can also use the --verbose to get some information about the authorization process.
Users
You can get the details of your user with the bb user me command:
bb user me
You can get the details of a user with the bb user get or bb user show command:
bb user get {UUID}
Or,
bb user get UUID
Workspaces
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 get your permission in a workspace with the bb workspace permission get command:
bb workspace permission get myworkspace
You can list all user permissions in a workspace with the bb workspace permission list command:
bb workspace permission list myworkspace
Projects
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:
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
Project Default Reviewers
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:
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:
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.
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):
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 :.
bb repo clone --username myusername myrepository
You can create a repository with the bb repo create command:
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
Pipelines
You can list pipelines with the bb pipeline list command:
bb pipeline list
By default the current repository is used, you can specify a repository with the --repository flag.
If there are too many pipelines and bb pipeline list seems to hang, you can use the --limit flag to set the maximum number of pipelines to retrieve. By default, the limit is set to 0, which means no limit.
You can get the details of a pipeline with the bb pipeline get or bb pipeline show command:
bb pipeline get 123456
You can start a pipeline with the bb pipeline trigger command:
By default, the pipeline is started on the current branch. You can also specify a tag or a commit with the --tag or --commit flags instead of a branch.
You can stop a running pipeline with the bb pipeline stop command:
bb pipeline stop 123456
You can get the list of the steps of a pipeline with the bb pipeline step list command:
bb pipeline step list --pipeline 123456
You can get the details of a step with the bb pipeline step get or bb pipeline step show command:
bb pipeline step get --pipeline 123456 {stepUUID}
You can get the logs of a step with the bb pipeline step log command:
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
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 \
--name \
--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
SSH Keys
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
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 \
--name \
--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
Cache
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
Completion
bb supports completion for Bash, fish, Powershell, and zsh.
Bash
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
fish
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
