Working with Bitbucket API

Bitbucket Cloud operations via the bb CLI wrapper (REST API v2, gh-style UX).

macOS tested, POSIX portable. bb auth login uses macOS Keychain (security) and open — these won't work on Linux. All other commands work on any POSIX system with curl and jq if you set BB_TOKEN and BB_EMAIL env vars.

Homebrew is an official dependency. bb installs from Quatico's tap by the short name quatico-bb. Trust the tap once, then brew install quatico-bb (or run install-dependencies.sh, which does it for you and migrates any older copied install):

brew tap quatico-solutions/tap
brew trust --tap quatico-solutions/tap
brew install quatico-bb

The fully qualified brew install quatico-solutions/tap/quatico-bb also works and auto-taps + auto-trusts.

Three unrelated Homebrew packages answer to bb. Only the tap is supported:

Install	What it is
brew install --cask bb	getbb.app, an IDE for coding agents
brew install bb-cli	a PHP Bitbucket CLI (bb-cli.github.io) with different commands, no api, no --json
brew install quatico-solutions/tap/quatico-bb	this CLI (supported)

bb --version prints bb <version> (quatico-bb — brew install quatico-solutions/tap/quatico-bb). If the output does not contain quatico-bb, stop and report which bb is installed. Do not install another package to fix it, and do not use a bare bb name in brew install.

Remote detection: If git remote get-url origin contains bitbucket.org, this is a Bitbucket repository — use bb CLI for all PR and source operations.

Step 0 (gate): confirm bb is installed and current — before any command

Before any bb command, check more than "does it run". A bb that merely works can be an older release that silently lacks newer subcommands or flags, or a leftover copy that Homebrew never installed and so never upgrades. Either way the command then fails in a way that looks like an API or auth problem when the real fix is an install or upgrade. Homebrew owns the install, so Homebrew answers the question:

command -v bb >/dev/null || echo "bb is not installed"   # exit 1 = absent; run install-dependencies.sh
bb --version | grep -q quatico-bb || echo "bb here is not quatico-bb"   # present but foreign: stop
bb --version                                    # missing counts as outdated
command -v bb                                   # must print "$(brew --prefix)/bin/bb" — anything else is a foreign bb earlier on PATH
readlink "$(brew --prefix)/bin/bb"              # non-zero: that path is not a Homebrew symlink, so Homebrew does not upgrade it
brew outdated quatico-bb                        # prints the formula when newer (auto-updates the tap, at most once every 24h)

brew list --formula is not the check: it reports the keg as installed even while the keg is unlinked and PATH still serves an old copied bb. The link and the PATH resolution are what say which binary actually runs.

If command -v bb fails, bb is absent: say bb is not installed and install it (below). If bb runs but bb --version does not contain quatico-bb, it is a different package: stop with one line, bb here is not quatico-bb (it prints: <first line of bb --version>) — install it with: brew install quatico-solutions/tap/quatico-bb. Do not install over it and do not continue.

If bb is missing, if command -v bb printed anything but $(brew --prefix)/bin/bb, if readlink failed (the bb that runs is a copy, not a Homebrew link), or if readlink printed a path under Cellar/bb/ (the keg still carries the formula's old name bb, which brew update does not migrate by itself), install it — no user approval needed, this is safe and idempotent:

bash "${CLAUDE_SKILL_DIR}/install-dependencies.sh"   # installs quatico-bb, migrates any old copy

If brew outdated printed the formula, upgrade it:

brew upgrade quatico-bb

Then check auth with bb whoami. If not logged in, tell the user to run bb auth login.

Never diagnose a bb command or auth error before ruling out a version mismatch. Do NOT silently fall back to curl or browser automation.

Exception: If the user explicitly prefers browser automation, or if the project's CLAUDE.md says to use working-with-bitbucket-web, honor that preference.

Tool Selection Decision Tree

Need to interact with Bitbucket?
├── List/view PRs? → bb pr list / bb pr view
├── Read PR comments? → bb pr view <id> --comments
├── Read only some PR fields? → bb pr view <id> --json number,state [--jq .state]
├── Post comment? → bb pr comment
├── Create PR? → bb pr create
├── Edit PR (reviewers, title, description, target branch)? → bb pr edit
├── Mark draft PR as ready? → bb pr edit <id> --ready
├── Approve PR? → bb pr review --approve
├── Merge PR? → bb pr merge
├── Close/decline PR? → bb pr close
├── List/resolve tasks? → bb pr tasks
├── Attach an image to a PR comment? → bb pr comment <id> --image <file>
├── Upload a file to the repo? → bb download upload <file>
├── Raw API call? → bb api <path>
└── SSO-gated page? → Browser (last resort)

bb handles everything including markdown in --body (descriptions, comments) and image uploads (via the repo Downloads area — see below). For multi-line descriptions or comments, use --body-file <path> (or - for stdin) on bb pr create, bb pr edit, or bb pr comment instead of interpolating a file through the shell. Browser is a last resort — only for SSO-gated pages.

Markdown: Bitbucket uses CommonMark, not GFM — no task lists, no strikethrough, no bare autolinks. Use the markdown skill if installed.

Authentication

Log in with an Atlassian API token:

bb auth login

Non-interactive (Claude Code / CI):

echo "$TOKEN" | bb auth login --email user@example.com

Verify with bb whoami (shows the account and whether the token came from BB_TOKEN or the keychain). Override with env vars: BB_TOKEN, BB_EMAIL.

Required API Token Scopes

Create an API token at https://id.atlassian.com/manage-profile/security/api-tokens with these scopes:

Minimum for full use (recommended): All five scopes above. Scope-to-command mappings are approximate — Bitbucket may require additional scopes depending on repository permissions.

Common failure mode: A token with only read scopes will list and view PRs successfully but fail with HTTP 400 or 401 on any write operation (commenting, approving, merging). Bitbucket error messages do not mention the missing scope — they just say "Bad Request" or "Token is not supported for this endpoint."

App passwords no longer work. Use API tokens.

Command Reference

Run bb --help for the full command list, or bb <command> <subcommand> --help for flags, defaults, and examples.

This skill is the single source of truth for the bb command surface. Do not maintain a local gh→bb translation/mapping table in a repo's CLAUDE.md/AGENTS.md. A copied local table duplicates this skill and drifts out of date — that is how stale, incorrect mappings spread (e.g. inventing a non-existent bb pr ready instead of bb pr edit <id> --ready). When a repo's agent-docs reference a gh command, translate it on the fly using this skill and bb --help, not from a hand-maintained table.

Listing pull requests (pr list)

bb pr list follows Bitbucket's next links, so the row count is the caller's choice:

bb pr list --state merged --limit 120                  # exactly 120 rows, across 3 pages
bb pr list --state merged --all --json number          # every page, no row limit
bb pr list --state merged --updated-since 2026-10-01   # only PRs updated at or after the bound
bb pr list --head feature/login --state merged  # the PR of one branch, in one request

• Without --limit or --all, pr list prints at most 50 rows. When more exist, it writes warning: listing truncated at 50 rows; use --limit or --all to stderr. Stdout stays pure JSON with --json.
• --all has no ceiling: about 75 requests per state on a repository with 3700 PRs. Use --limit or --updated-since to read less. --all and --limit cannot be combined.
• --updated-since <ISO> filters on the server and is inclusive (>=), so a caller that reads again from its last watermark gets the boundary PR twice, never zero times. It forces the q= filter form, like --author.
• --head <branch> filters on the source branch on the server. Repeat it to cover several branches. It forces the q= filter form, like --author, and keeps the open default for --state: a merged branch needs --state merged. A branch name containing " exits 1, because Bitbucket documents no escape rule for it.
• Bitbucket returns PRs newest-updated first. pr list has no --sort.
• Every paged listing retries a page that answers HTTP 429 up to 5 times (Retry-After seconds up to 60, otherwise 2, 4, 8, 16 and 32 s), and prints bb: rate limited, retrying in <n> s (<k>/5) on stderr before each wait. A long --all can therefore pause for up to a minute per page. After the last retry it exits 75 with error: rate limited after <n> rows (plus — Bitbucket asked to wait <s> s when the final answer carries Retry-After, printed as sent) and prints no rows, so a short list never looks complete.

Targeting another repository (-R)

By default bb auto-detects the workspace/repo from the current directory's origin remote. To operate on a different repo — or from a directory that is not a Bitbucket checkout at all — pass the global -R workspace/repo flag before the subcommand:

bb -R quatico/other-repo source ls
bb -R quatico/other-repo source cat README.md --ref develop
bb -R quatico/other-repo pr list

-R is global, so it works for every command (source, pr, api, …). It must come before the subcommand — bb source cat -R … will not work. Without -R, source browsing and all other operations act on the current repo only.

Merging with a head check (bb pr merge --match-head-commit)

bb pr merge <id> merges whatever the PR head is when the request arrives. To refuse a PR that moved after review, pin the head, like gh pr merge --match-head-commit:

bb pr merge 42 --squash --match-head-commit "$(git rev-parse HEAD)"

bb reads the PR, then merges only if its head and the pin match. The pin is 7 or more hex digits; uppercase is lowercased. Bitbucket reports a 12-character head hash, so the comparison is a prefix match in both directions and a full 40-character SHA works. A malformed pin is a usage error with no request sent. A mismatch exits 1 with error: head moved — …; nothing was merged and sends no merge request.

Race: the merge endpoint takes no expected head, so a push between the read and the merge is merged anyway. bb runs no check after the merge. The flag narrows the window; it does not close it.

Raw API Access

For API endpoints not yet wrapped by bb commands, use bb api as an escape hatch:

bb api /repositories/{ws}/{repo}                        # GET (default)
bb api repositories/{ws}/{repo}                         # leading slash is optional
bb api /repositories/{ws}/{repo}/pullrequests/42/decline --method POST
bb api /repositories/{ws}/{repo}/pullrequests --method POST --data '{"title":"test"}'

{ws} and {repo} are auto-replaced with the current repo's workspace and slug — or with the repo named by a global -R workspace/repo flag (see Targeting another repository).

The leading / is optional. A full URL on the API base (https://api.bitbucket.org/2.0/…, such as a next link from a listing) is accepted. Any other URL exits 1 without sending a request, because bb sends the token with every call.

Calling bb from a script

bb exits non-zero when a request fails, including when no HTTP answer arrives (error: no response from Bitbucket). A script must check that exit status. When a script pipes bb into another command, it must run set -o pipefail first: without it the pipeline reports the exit status of the last command, and a failed bb looks like success.

Attaching Images to PRs (no browser)

Images can be attached to PR comments and descriptions entirely via the API — no browser required. Bitbucket's repo Downloads area accepts multipart file uploads; you then reference the resulting URL with CommonMark image syntax.

One step (recommended) — bb pr comment --image uploads and references the image for you:

bb pr comment 42 --image before-after.png --body "Layout regression below:"

Repeat --image for multiple images. Each is uploaded under a pr<id>- prefixed name (avoids cross-PR collisions) and appended to the body as ![name](url).

Two steps — upload, then reference the URL yourself (e.g. in a PR description):

url="$(bb download upload pr42-diff.png)"     # prints the download URL
bb pr edit 42 --body "## Screenshots

![diff]($url)"

bb download list shows what's currently in the Downloads area.

Caveats

• The download URL is private — it returns 401 to unauthenticated requests but renders inline for reviewers viewing the PR in an authenticated browser. This is expected and fine.
• Downloads are repo-global (not scoped to a PR) and collide by name — a re-upload with the same name overwrites the previous file. Use unique, prefixed names (the --image flow does this automatically).
• bb api can't do uploads: it only sends JSON bodies. Use bb download upload / bb pr comment --image, which send multipart/form-data.

Fallback: Browser Automation

Use working-with-bitbucket-web skill only when:

• SSO-gated pages that require browser authentication

Image uploads don't need a browser — use bb pr comment --image or bb download upload (see above).

Integration