KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

bitbucket-cli

★ 57 Open GitHub ↗

Bitbucket CLI

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Bitbucket Command Line Interface

[bb](https://github.com/gildas/bitbucket-cli) 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 binary package on the [Downloads](https://github.com/gildas/bitbucket-cli/releases) pages.

On Debian/Ubuntu distributions, you can use my package repository. First download the signing key:

```bash
curl -fsSL https://gildas.github.io/apt/gildas-archive-keyring.gpg | \
  sudo tee /usr/share/keyrings/gildas-archive-keyring.gpg >/dev/null
```

Add this source:

```bash
echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/gildas-archive-keyring.gpg] https://gildas.github.io/apt stable main" | sudo tee /etc/apt/sources.list.d/gildas.list
sudo apt update
```

Then install `bb` with:

```bash
sudo apt install bitbucket-cli
```

If you use [Homebrew](https://brew.sh), you can install `bb` with:

```bash
brew install gildas/tap/bitbucket-cli
```

You can also install `bb` with snap:

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

[![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-black.svg)](https://snapcraft.io/bitbucket-cli)

### macOS

You can get `bb` from [Homebrew](https://brew.sh) with:

```bash
brew install gildas/tap/bitbucket-cli
```

### Windows

You can get `bb` from [Chocolatey](https://chocolatey.org) with:

```bash
choco install bitbucket-cli
```

You can also install `bb` with [scoop](https://scoop.sh):

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

### Go

If you have Go installed, you can install `bb` with:

```bash
go install github.com/gildas/bitbucket-cli@latest
mv $GOPATH/bin/bitbucket-cli $GOPATH/bin/bb
```

This method also allows you to install `bb` from the development (`dev`) branch with:

```bash
go install github.com/gildas/bitbucket-cli@dev
mv $GOPATH/bin/bitbucket-cli $GOPATH/bin/bb
```

### Binaries

You can download the latest version of `bb` from the [downloads](https://github.com/gildas/bitbucket-cli/releases) page.

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

## Usage

`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](#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:

```bash
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.

```bash
bb repo delete myrepository3 --dry-run
```

Most commands will support the `--workspace` and `--repository` flags to specify the workspace and repository to use. If not provided, the workspace and repository will be determined from the git configuration or the profile configuration (in that order). The workspace and repository can be combined in the `--repository` flag in the form `workspace/repository`. For example:

```bash
bb repo list --workspace myworkspace
bb pullrequest list --repository myrepository
bb pullrequest list --workspace myworkspace --repository myrepository
bb pullrequest list --repository myworkspace/myrepository
```

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

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

```bash
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.

```bash
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:

```bash
bb pullrequest list --query 'updated_on > 2025-12-31'
```

Please refer to the [Bitbucket API documentation](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#filtering) 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.

```bash
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](#profiles)).

The following formats are supported:

- `csv`: CSV
- `json`: JSON
- `yaml`: YAML
- `tsv`: TSV
- `table`: Table

For example:

```bash
bb --output json workspace list
```

```bash
bb workspace list --output json
```

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

```bash
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:

### Profiles

#### Setting up OAUTH 2.0

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 clients` link in the `Apps and features` section. Then click on the `Create OAuth client` button. Fill in the form.

![OAuth clients](https://raw.githubusercontent.com/gildas/bitbucket-cli/dev/images/bitbucket-add-oauth.png)

To use an [OAuth 2.0 with Authorization Code Grant](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#1--authorization-code-grant--4-1-), 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](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#3--client-credentials-grant--4-4-), you will need to enable the check box for `This is a private consumer` and add a _dummy_ `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`.

#### Managing Profiles

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

```bash
bb profile create \
  --name              myprofile \
  --default-workspace myworkspace \
  --client-id         <your-client-id> \
  --client-secret     <your-client-secret> \
  --callback-port     8080
```

You should define the default workspace for the profile with the `--default-workspace` flag. This will allow you to use `bb` without specifying the workspace every time.

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. If you use only one profile, it will be used as the default profile.

You can also pass the `--default-project` flag to set the default project for this profile.

You can also pass the `--default-ssh-key-file` flag to set the default SSH key file to use when cloning repositories with the `ssh` protocol.

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.

Once the profile is created in `bb`, for an [OAuth 2.0 with Authorization Code Grant](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#1--authorization-code-grant--4-1-), you will need to authorize the profile with the following command:

```bash
bb profile authorize myprofile
```

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

Profiles support the following authentications:

- [OAuth 2.0 with Authorization Code Grant](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#1--authorization-code-grant--4-1-) with the `--client-id`, `--client-secret`, and `--callback-port` flags. See the [Setting Up an OAUTH 2.0 Profile](#setting-up-oauth-20) section for more information about how to create an OAuth client and authorize the profile.
- [OAuth 2.0 with Client Credentials](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#3--client-credentials-grant--4-4-) with the `--client-id` and `--client-secret` flags. See the [Setting Up an OAUTH 2.0 Profile](#setting-up-oauth-20) section for more information about how to create an OAuth client.
- [API tokens](https://support.atlassian.com/bitbucket-cloud/docs/api-tokens/) with the `--user` and `--password` flags. The user is the **Atlassian account email** and the password is the API token in this case.
- ~~[App passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/) with the `--user` and `--password` flags.~~ [App passwords are deprecated by Atlassian in favour of API tokens as of June 9, 2025 and will stop working entirely on June 9, 2026](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation). Use API tokens instead.
- [Repository Access Tokens](https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens/), [Project Access Tokens](https://support.atlassian.com/bitbucket-cloud/docs/project-access-tokens/), [Workspace Access Tokens](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/) with the `--access-token` flags. Using Project/Workspace Access Tokens requires a Premium plan on Bitbucket Cloud. Using Repository Access Tokens does not require a Premium plan, but the token will only have access to the repository it was created for.

Permission Scopes:

- [OAuth 2.0 scopes](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#bitbucket-oauth-2-0-scopes)
- [API token permissions](https://support.atlassian.com/bitbucket-cloud/docs/api-token-permissions/)

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:

```bash
bb profile list
```

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

```bash
bb profile get myprofile
```

You can ge the details of the current profile:

```bash
bb profile get --current
```

Or:

```bash
bb profile which
```

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

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

If the profile was not using the vault to store the credentials and you update it with new credentials, the updated profile will keep using plain text to store the credentials. If the profile was using the vault and you update it with new credentials, the updated profile will keep using the vault to store the credentials.

You can move the profile credentials to the vault with the `bb profile update`:

```bash
bb profile update myprofile --to-vault
```

During that process, you cannot change the credentials. But you can specify the vault key for non Windows OS with the `--vault-key` flag:

```bash
bb profile update myprofile --to-vault --vault-key my-vault-key
```

The default vault key is `bitbucket-cli`.

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

```bash
bb profile delete myprofile
```

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

```bash
bb profile use myprofile
```

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

```bash
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:

```ini
[bitbucket "cli"]
  profile = myprofile
```

```bash
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:

```bash
export BB_CONFIG=~/.bb/config.json
```

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

### Users

You can get the details of your user with the `bb user me` command:

```bash
bb user me
```

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

```bash
bb user get {UUID}
```

Or,

```bash
bb user get UUID
```

### Workspaces

You can list workspaces with the `bb workspace list` command:

```bash
bb workspace list
```

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

```bash
bb workspace list --membership
```

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

```bash
bb workspace get myworkspace
```

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

```bash
bb workspace get myworkspace --members
```

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

```bash
bb workspace get myworkspace --member mymember
```

You can get your permission in a workspace with the `bb workspace permission get` command:

```bash
bb workspace permission get myworkspace
```

You can list all user permissions in a workspace with the `bb workspace permission list` command:

```bash
bb workspace permission list myworkspace
```

### Projects

You can list projects with the `bb project list` command:

```bash
bb project list
```

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

```bash
bb project get myproject
```

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

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

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

```bash
bb project update myproject \
  --name myproject
```

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

```bash
bb project delete myproject
```

#### Project Default Reviewers

You can list the default reviewers of a project with the `bb project reviewer list` command. Similarly 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):

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

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

```bash
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:

```bash
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:

```bash
bb project reviewer get --project myproject userUUID
```

### Repositories

You can list repositories with the `bb repo list` command:

```bash
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:

```bash
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:

```bash
bb repo get myrepository
```

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

```bash
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:

```bash
bb repo clone --workspace myworkspace myrepository
```

Or, using the profile's default workspace:

```bash
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:

```bash
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.

```bash
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`):

```bash
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>`.

```bash
bb repo clone --username myusername myrepository
```

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

```bash
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:

```bash
bb repo update myrepository \
  --private \
  --fork-policy no_public_forks
```

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

```bash
bb repo delete myrepository
```

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

```bash
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:

```bash
bb repo get myrepository --forks
```

### Branches

You can list branches with the `bb branch list` command:

```bash
bb branch list
```

### Commits

You can list commits with the `bb commit list` command:

```bash
bb commit list
```

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

```bash
bb commit get 123456
```

While the completion for commit hashes works, it can be a bit slow if there are a lot of commits in the repository. If you know the first few characters of the commit hash, it will be much faster to complete. You also do not need to enter the full commit hash, the first 7 characters are usually enough to identify a commit. But less can be enough if there are not many commits in the repository.

You can get the difference between two commits with the `bb commit diff` command:

```bash
bb commit diff 123456 654321
```

If you provide only one commit, the difference will be between that commit and its parent:

```bash
bb commit diff 123456
```

If you want to get the diffstat of a commit, you can use the `--stat` flag:

```bash
bb commit diff --stat 123456
```

You can get the common ancestor of two commits with the `bb commit ancestor` command:

```bash
bb commit ancestor 123456 654321
```

You can also get the patch between two commits with the `bb commit patch` command:

```bash
bb commit patch 123456 654321
```

### Tags

You can list tags with the `bb tag list` command:

```bash
bb tag list
```

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

```bash
bb tag get v1.0.0
```

You can create a tag with the `bb tag create` command:

```bash
bb tag create v1.0.0 \
  --message "My tag message" \
  --target 123456
```

By default, the target of the tag is the latest commit on the default branch.

You can delete tags with the `bb tag delete` command:

```bash
bb tag delete v1.0.0
```

### Pull Requests

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

```bash
bb pullrequest list
```

You can get the list of pull requests for a given commit hash (it must be the full hash) with the `--commit` flag:

```bash
bb pullrequest list --commit ae86d5323477989fab3bf3879cd1234543565753
```

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

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

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

```bash
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:

```bash
bb pullrequest get 1
```

You can also modify a pull request with the `bb pullrequest update` command:

```bash
bb pullrequest update 1 \
  --title "My pull request" \
  --description "My pull request description"
```

To add or remove reviewers from a pull request, you can use the `--add-reviewer` and `--remove-reviewer` flags:

```bash
bb pullrequest update 1 \
  --add-reviewer    username1 --add-reviewer {userUUID2} \
  --remove-reviewer username3 --remove-reviewer {userUUID4}
```

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

```bash
bb pullrequest approve 1
```

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

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

```bash
bb pullrequest decline 1
```

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

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

```bash
bb pullrequest merge 1
```

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

You can also merge the pull request asynchronously with the `--async` flag:

```bash
bb pullrequest merge 1 --async
```

In that case, you will receive a merge task ID in return, and you can check the status of the merge task with the `bb pullrequest merge-status` command:

```bash
bb pullrequest merge-status 1 --task-id 6a0ddb61-40cf-4224-b9e8-bbb5852c66ba
```

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

You can request changes on a pull request with the `bb pullrequest request-changes` command:

```bash
bb pullrequest request-changes 1
```

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

To remove the request for changes, you can use the `bb pullrequest remove-request-changes` command:

```bash
bb pullrequest remove-request-changes 1
```

If no pull request is provided, the command will try to remove the request for changes on the opened pull request with the current branch.

You can see the activities of a pull request with the `bb pullrequest activities` command:

```bash
bb pullrequest activities 1
```

If no pull request is provided, the command will try to list the activities of the opened pull request with the current branch.

You can list the commits of a pull request with the `bb pullrequest commits` command:

```bash
bb pullrequest commits 1
```

If no pull request is provided, the command will try to list the commits of the opened pull request with the current branch.

You can see the diff of a pull request with the `bb pullrequest diff` command:

```bash
bb pullrequest diff 1
```

If no pull request is provided, the command will try to show the diff of the opened pull request with the current branch.

You can get the diffstat of a pull request with the `bb pullrequest diff --stat` command:

```bash
bb pullrequest diff --stat 1
```

If no pull request is provided, the command will try to show the diffstat of the opened pull request with the current branch.

You can also get the patch of a pull request with the `bb pullrequest patch` command:

```bash
bb pullrequest patch 1
```

If no pull request is provided, the command will try to show the patch of the opened pull request with the current branch.

#### Pull Request Comments

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

```bash
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:

```bash
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:

```bash
bb pullrequest comment resolve --pullrequest 1 452466
```

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

```bash
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:

```bash
bb pullrequest comment get --pullrequest 1 452466
```

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

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

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

```bash
bb pullrequest comment delete --pullrequest 1 452466
```

#### Pull Request Tasks

You can list the tasks of a pull request with the `bb pullrequest task list` command:

```bash
bb pullrequest task list --pullrequest 1
```

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

```bash
bb pullrequest task create --pullrequest 1 \
  --content "My task"
```

You can reference a comment in a task with the `--comment` flag:

```bash
bb pullrequest task create --pullrequest 1 \
  --content "My task" \
  --comment 452466
```

You can complete a task with the `bb pullrequest task update` command:

```bashbb pullrequest task update --pullrequest 1 7643545 \
  --state RESOLVED
```

You can also re-open a task with the same command:

```bashbb pullrequest task update --pullrequest 1 7643545 \
  --state UNRESOLVED
```

You can delete a task with the `bb pullrequest task delete` command:

```bash
bb pullrequest task delete --pullrequest 1 7643545
```

### Issues

You can list issues with the `bb issue list` command:

```bash
bb issue list
```

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

```bash
bb issue list --state open
```

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

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

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

```bash
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:

```bash
bb issue get 1
```

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

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

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

```bash
bb issue delete 1
```

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

```bash
bb issue vote 1
```

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

```bash
bb issue unvote 1
```

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

```bash
bb issue watch 1
```

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

```bash
bb issue unwatch 1
```

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

```bash
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:

```bash
bb issue comment get --issue 1 7643545
```

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

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

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

```bash
bb issue comment delete --issue 1 7643545
```

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

```bash
bb issue attachment list --issue 1
```

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

```bash
bb issue attachment upload --issue 1 myattachment.zip
```

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

```bash
bb issue attachment download --issue 1 myattachment.zip
```

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

```bash
bb issue attachment delete --issue 1 myattachment.zip
```

### Artifacts (Downloads)

You can list artifacts with the `bb artifact list` command:

```bash
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:

```bash
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:

```bash
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:

```bash
bb artifact delete myartifact.zip
```

### Pipelines

You can list pipelines with the `bb pipeline list` command:

```bash
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:

```bash
bb pipeline get 123456
```

You can start a pipeline with the `bb pipeline trigger` command:

```bash
bb pipeline trigger --branch master --variable KEY1=VALUE1 --variable KEY2=VALUE2
```

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 also use the `--pattern` flag to specify the pipeline definition to use when triggering the pipeline.

You can stop a running pipeline with the `bb pipeline stop` command:

```bash
bb pipeline stop 123456
```

You can get the list of the steps of a pipeline with the `bb pipeline step list` command:

```bash
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:

```bash
bb pipeline step get --pipeline 123456 {stepUUID}
```

You can get the logs of a step with the `bb pipeline step log` command:

```bash
bb pipeline step logs --pipeline 123456 {stepUUID}
```

### GPG Keys

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

```bash
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:

```bash
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:

```bash
bb gpg-key create \
  --user <user-id> \
  --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. If it is provided, it must be the UUID of the user, not the username.

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

```bash
bb gpg-key delete <fingerprint>
```

### SSH Keys

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

```bash
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:

```bash
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:

```bash
bb ssh-key create \
  --user <user-id> \
  --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. If it is provided, it must be the UUID of the user, not the username.

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

```bash
bb ssh-key delete <fingerprint>
```

### 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](https://pkg.go.dev/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](https://pkg.go.dev/github.com/gildas/go-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](https://pkg.go.dev/crypto/aes) requirements.

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

```bash
bb cache clear
```

### Completion

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

#### Bash

To enable completion, run the following command:

```bash
source <(bb completion bash)
```

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

```bash
bb completion bash > ~/.bashrc
```

#### fish

To enable completion, run the following command:

```bash
bb completion fish | source
```

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

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

#### Powershell

To enable completion, run the following command:

```pwsh
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.

#### zsh

To enable completion, run the following command:

```bash
source <(bb completion zsh)
```

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

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

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

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

### Obtaining logs for debugging

If you encounter an issue with `bb`, you can obtain logs to help with debugging.

You can instruct `bb` to log its activity by using the `--log` flag:

```bash
bb --log tmp/bb.log workspace list
```

or with the environment variable `LOG_DESTINATION`:

```bash
LOG_DESTINATION=tmp/bb.log bb workspace list
```

`bb` will create the log file as needed (but it will not create the parent directories). By default, the log level is set to `info`, but you can set it to `debug` to get more detailed logs:

```bash
LOG_LEVEL=DEBUG bb --log tmp/bb.log workspace list
```

You can also set these environment variables in a `.env` file in the current directory, and `bb` will automatically load them:

```bash
LOG_DESTINATION=tmp/bb.log
LOG_LEVEL=DEBUG
```

If you set the log level to DEBUG or more, `bb` will also log the source of the log message (file and line number, function name).

`bb` will write log messages following the format in [gildas/go-logger](https://github.com/gildas/go-logger). You can find some extra information about the log configuration in the documentation of that package. You can use [gildas/lv](https://github.com/gildas/lv) or [The Bunyan log viewer](https://github.com/trentm/node-bunyan) to view the logs in a human readable format.

**Notes**:

- `bb` tries hard to not log sensitive information, but be careful when sharing the logs, and make sure to remove any sensitive information before sharing them. You can open an [issue](https://github.com/gildas/bitbucket-cli/issues) if you feel like `bb` is logging sensitive information it should not. (We will do our best to fix it as soon as possible)
- If you set the log level to `TRACE`, the logs will contain the full HTTP requests and responses, including headers and body. This can be useful for debugging, but it can also contain sensitive information, so be careful when sharing these logs.
- When sending the logs to our team, please send the JSON version, not the pretty printed version, as it will be easier to analyze.

## TODO

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

We are in the process of adding support for Bitbucket Server/Data Center. (Issue [#65](https://github.com/gildas/bitbucket-cli/issues/65), Branch [feature/Issue-#65-Datacenter](https://github.com/gildas/bitbucket-cli/tree/feature/Issue-%2365-Datacenter))

## Stargazers over time

[![Stargazers over time](https://starchart.cc/gildas/bitbucket-cli.svg?variant=adaptive)](https://starchart.cc/gildas/bitbucket-cli)

bitbucket-cli

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README