bb — Bitbucket CLI

bb is a fast, gh-style command line for Bitbucket Cloud and Bitbucket Data Center/Server. It gives you pull requests, repos, issues, pipelines, and more from your terminal — with human-readable tables by default and a --json flag on every list/view command for scripts and agents.

bb pr list
bb pr create --title "Fix login bug"
bb repo clone myteam/myrepo

Install

The recommended install puts a bb command on your PATH — no prefixes, no activation:

# once published to PyPI:
pip install bitbucket-client   # or: uv tool install bitbucket-client
# from a clone:
uv tool install .
bb --help

The PyPI package is bitbucket-client (bitbucket-cli, bb, and bb-cli were already taken). The installed command is always bb.

git clone https://github.com/ml-lubich/bitbucket-cli
cd bitbucket-cli
./scripts/setup.sh                              # installs uv if missing, then syncs
UV_PROJECT_ENVIRONMENT=venv uv run bb --help    # run inside the project venv

Authenticate

bb targets Bitbucket Cloud by default. On Bitbucket Cloud in an interactive terminal, just log in through your browser:

bb auth login          # opens your browser for Atlassian SSO (OAuth 2.0)
bb auth status         # confirm you're logged in

bb stores an access token plus a rotating refresh token in your OS keyring and refreshes them automatically — you won't log in again until the refresh token is revoked or expires. See docs/AUTH.md for the full flow and how to use your own OAuth consumer.

Token login (Data Center, CI, or any non-interactive shell):

bb config set base_url https://bitbucket.example.com   # Data Center only
bb auth login --token "$YOUR_TOKEN"
echo "$YOUR_TOKEN" | bb auth login --with-token        # from stdin

• Data Center HTTP access tokens (often BBDC-…) use Bearer auth against https://your-host/rest/api/1.0.
• Atlassian API tokens (ATATT…) use Basic auth — pass --username <email> or set BITBUCKET_EMAIL / BB_USERNAME.

bb also reads a token from the environment (first match wins): BB_TOKEN, BITBUCKET_TOKEN, BITBUCKET_AUTH_TOKEN, or a BB_TOKEN=… line in a repo-local .env. Never commit tokens — use env vars or your CI secret store.

Other auth commands: bb auth refresh (force refresh), bb auth setup-git (print git -c flags for authenticated HTTPS), bb auth logout.

Quick start

# Pull requests
bb pr list
bb pr list --state MERGED --limit 10
bb pr create --title "Fix login bug"
bb pr merge 42 --merge-strategy squash --delete-branch

# Repositories
bb repo list --workspace myteam
bb repo clone myteam/myrepo
bb repo create --name new-service --workspace myteam

# Issues
bb issue list
bb issue create --title "Crash on startup" --kind bug --priority critical
bb issue close 7

# Pipelines
bb pipeline list
bb pipeline run --branch main
bb pipeline logs abc-uuid-1234
bb pipeline variable create --key API_KEY --value secret --secured

# Search & status
bb search repos myservice --workspace myteam
bb search code "TODO" --workspace myteam
bb status            # you + PRs awaiting your review

Add --json to any list/view command for machine-readable output, and bb doctor --json for agent-friendly setup/auth diagnostics.

Commands

Help is available at every level: bb --help, bb <group> --help, bb <group> <subcommand> --help (or -h).

Use bb from a coding agent (MCP)

bb mcp serve runs a read-only Model Context Protocol server over stdio, so Claude, Codex, and other agents can query Bitbucket directly — no shell glue. It reuses your existing bb auth and, because bb maps Cloud paths to Data Center automatically, the same tools work against on-prem hosts.

Tools exposed: whoami, repo_list, repo_view, pr_list, pr_view, issue_list, pipeline_list, and api_get (any read-only GET path). Every tool is a GET — nothing can mutate your data.

Point an MCP client at the command bb mcp serve. For Claude Code:

claude mcp add bitbucket -- bb mcp serve

Coming from gh?

bb mirrors GitHub CLI ergonomics where Bitbucket has an equivalent:

Where Bitbucket differs from GitHub:

• No bb pr reopen — Bitbucket Cloud can't reopen a declined PR (the command exits with a clear message).
• No bb pr ready, bb repo rename, or bb repo archive — no Cloud API for them.
• No label or release commands — Bitbucket Cloud has no analog.
• Pipelines are referenced by UUID, not a numeric run ID.
• Issue --kind values: bug, enhancement, proposal, task.
• Browser login is Cloud-only; Data Center always uses --with-token.

Configuration

Settings resolve top-down (first match wins):

Keys (valid in both bb.toml and config.toml):

bb config set base_url https://bitbucket.example.com
bb config set default_workspace myteam
bb config set git_protocol ssh
bb repo set-default myteam/myrepo    # writes default_repo to bb.toml at the git root

Set BB_REPO=workspace/slug to pin the target repo anywhere (CI, scripts, or outside a clone). Set NO_COLOR to disable colored output.

Docs

• Architecture
• Authentication — OAuth flow, refresh model, security notes
• API reference
• Testing · Runbook · Agent usage
• Publishing · Changelog

MIT License · Copyright (c) 2026 Misha Lubich (ml-lubich) · mishalubich.com