Bitbucket Cloud from your terminal: pull requests, pipelines, repositories and more, with JSON output on every command.
Docs · Quick Start · Command Reference · Changelog · Issues
Note: This is an unofficial, community-maintained CLI for Bitbucket Cloud.
It is not affiliated with or endorsed by Atlassian. Bitbucket Server and Data Center are not supported.
- The whole pull request loop: create, review, comment, resolve threads, approve and merge without leaving the terminal
- CI included: trigger pipelines, wait for them to finish, follow their logs, inspect deployments and set build statuses
- Repository admin: webhooks, branch restrictions, default reviewers, downloads, and your SSH and GPG keys
- Built for scripts and AI agents:
--jsonon every command, field projection, and a built-in--jq(nojqbinary needed) - Zero setup per repo: workspace and repository are picked up from your git remote
- Escape hatch:
bb apicalls any Bitbucket Cloud 2.0 endpoint with your credentials
Standalone binary (no runtime needed). Every GitHub Release since v2.2.0 ships bb for Linux, macOS and Windows, with a SHA256SUMS file and build provenance attestations. The install script picks your platform and verifies the checksum:
# Linux and macOS
curl -fsSL https://github.com/0pilatos0/bitbucket-cli/releases/latest/download/install.sh | sh# Windows
irm https://github.com/0pilatos0/bitbucket-cli/releases/latest/download/install.ps1 | iexSee the installation guide for options, archives and manual downloads.
npm package, which runs on Bun 1.1.30 or newer (not Node.js):
curl -fsSL https://bun.sh/install | bash # if `bun --version` fails
npm install -g @pilatos/bitbucket-cli # or: bun install -g / pnpm add -gOn Windows, --jq needs Bun 1.4.2 or newer.
Then turn on tab completion (optional, recommended) and restart your shell:
bb completion installFull details: Installation.
bb auth login # opens your browser to sign in
cd your-bitbucket-checkout
bb pr listID TITLE AUTHOR BRANCHES
--- -------------------------------------- ------------ -----------------------
#47 Stream pipeline logs while a step runs Ada Lovelace feat/stream-logs → main
#46 Retry on 429 rate limits Grace Hopper fix/retry-429 → main
A few more to get a feel for it:
bb pr create --title "Add feature" # from the current branch
bb pr checkout 46 # review it locally
bb pr approve 46
bb pr merge 47 --strategy squash --close-source-branch
bb pipeline run --branch main
bb pipeline watch # wait for this branch's latest run
bb pipeline logs 313 --follow
bb repo cat package.json --ref main # read a file without cloning
bb browse 42 # open PR #42 in your browser
bb api /user # any Bitbucket API endpoint| Command | What it does |
|---|---|
pr |
Pull requests: create, edit, review, comments, reviewers, checks, diff, merge |
repo |
Clone, create, list, delete; read files and folders; downloads |
pipeline |
List, run, stop, watch and follow logs of Bitbucket Pipelines |
deployment |
Deployments and environments |
commit |
List and inspect commits |
status |
Read and set build statuses on a commit |
branch-restriction |
Branch protection rules |
webhook |
Repository and workspace webhooks |
search |
Code search across a workspace |
snippet |
Snippets and their comments |
workspace / project |
Discover workspaces; list, view and create projects |
ssh-key / gpg-key |
Keys on your own account |
browse |
Open a repo, file, PR or commit in your browser |
api |
Authenticated request to any Bitbucket Cloud 2.0 endpoint |
auth, config, alias, completion |
Login, settings, command shortcuts, shell completion |
Use -w/--workspace and -r/--repo to select the target for commands that need workspace or repository context. Run bb help <command> for flags and examples, or see Global Flags.
--json accepts an optional comma-separated field list, and --jq filters the result in-process:
# Only the fields you need
bb pr list --json id,title,state
# Filter with the built-in jq
bb pr list --json --jq '.pullRequests[] | select(.author.display_name == "Ada Lovelace") | .id'
# Capture a value
build=$(bb pipeline run --branch main --json --jq '.pipeline.build_number')
# Block until it finishes; exits non-zero unless it passes
bb pipeline watch "$build"Command prompts are disabled when stdin or stdout is not a terminal, with --json, or with --no-input. The completion installer has its own interactive prompts. See JSON Output, the Scripting guide and CI/CD.
Interactive login lets you choose OAuth or an API token. API-token login uses your Atlassian account email, even though the flag is named --username and the environment variable is BB_USERNAME.
-
OAuth (default):
bb auth loginopens your browser. Tokens refresh automatically. The browser must reach the callback on this machine. Use API-token login on headless hosts. -
API token (CI and headless hosts): create one in your Bitbucket settings, then:
printf '%s' "$BB_API_TOKEN" | bb auth login -u you@example.com --with-token
OAuth permissions come from the consumer configured in Bitbucket. For workflows that need other permissions, use a scoped API token or a custom consumer; see Token Scopes.
Bitbucket app passwords stopped working on July 28, 2026. If you still log in with one, switch to OAuth or an API token.
More: Authentication.
The variables you're most likely to need:
| Variable | Description |
|---|---|
BB_USERNAME / BB_API_TOKEN |
Credentials picked up by bb auth login, handy in CI |
BB_WORKSPACE |
Default workspace when you're not inside a checkout |
BB_DEBUG |
http traces every API call with status and timing; verbose adds the bodies |
Persistent settings live in bb config (for example bb config set defaultWorkspace myworkspace). Everything else, including timeouts, locale and color: Environment Variables and Configuration.
Full docs live at bitbucket-cli.paulvanderlei.com:
- Quick Start and Command Reference
- Guides: Scripting, CI/CD, AI agents (Claude Code, opencode, Cursor, Windsurf)
- Recipes for common automation
- Troubleshooting, FAQ and Changelog
Read the Contributing Guide to get started.
- Inspired by GitHub CLI (
gh) - Runs on Bun, built with Commander.js
- API client generated from the Bitbucket Cloud REST API OpenAPI spec
MIT License. See LICENSE for details.