bb — Bitbucket Cloud CLI

Open pull requests, read every comment, and write replies — without leaving the shell or opening a browser tab.

One binary, no runtime to install. Your API token lives in your OS keyring and is never printed, never written to disk, and never sent anywhere except api.bitbucket.org over TLS. bb update is the one command that talks to another host — it queries the GitHub Releases API without sending any credentials.

$ bb pr list
┌────┬──────────────────────────┬─────────────────┬───┬────────┬────────┬────────────┬──────────┐
│ ID ┆ TITLE                    ┆ SOURCE          ┆ → ┆ TARGET ┆ AUTHOR ┆ REVIEWERS  ┆ APPROVED │
╞════╪══════════════════════════╪═════════════════╪═══╪════════╪════════╪════════════╪══════════╡
│ 42 ┆ Cache session lookups    ┆ feat/cache      ┆ → ┆ main   ┆ dev    ┆ Ada, Linus ┆ Ada      │
│ 41 ┆ Fix token refresh window ┆ fix/token-clock ┆ → ┆ main   ┆ dev    ┆ Linus      ┆          │
└────┴──────────────────────────┴─────────────────┴───┴────────┴────────┴────────────┴──────────┘

Install

Homebrew, the prebuilt archives, and cargo binstall all install a compiled binary and need no Rust toolchain at all; only building from source requires one, with a 1.88 floor.

Homebrew (macOS and Linux):

brew install biokraft/tap/bb

Prebuilt binary — download the archive for your platform from the latest release, verify it against the accompanying .sha256 file, and put bb on your PATH. Supported targets: aarch64-apple-darwin, x86_64-apple-darwin, x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu.

Install script — detects your platform, verifies the checksum, installs to ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/biokraft/bbcloud/main/install.sh | sh

cargo-binstall — fetches the same prebuilt binary, no compiler needed:

cargo binstall bbcloud

From source — needs Rust 1.88 or newer:

cargo install bbcloud --locked

That installs bb into ~/.cargo/bin. If the command isn't found afterwards, put that directory on your PATH:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc && exec zsh

Authenticate

Atlassian removed Bitbucket Cloud app passwords on 2026-07-28. bb uses an Atlassian API token, sent as HTTP Basic auth with your account email as the username.

1. Create a token at https://id.atlassian.com/manage-profile/security/api-tokens, selecting the scopes below.
2. Run bb auth login and paste it — the input is masked and never echoed.

bb auth login     # prompts, verifies the token, then stores it in the OS keyring
bb auth logout    # removes the stored credentials
bb auth status    # shows the account; the token is always redacted to ****last4

Token scopes

Grant the least you need. For the pull request workflow — listing, reading and commenting — four scopes are enough:

One gotcha worth knowing: write:pullrequest:bitbucket does not imply read:repository:bitbucket, so pr create needs both.

CI and headless machines

There is no keyring on a CI runner, and on Linux the keyring backend is secret-service, which is absent on servers. Set the credentials in the environment instead — they are checked before the keyring, so this also works as a local override:

export BB_EMAIL='you@example.com'
export BB_TOKEN='...'
bb pr list --json

Check it works

bb --version
bb auth status                              # exits 2 until you log in
cd any-bitbucket-repo && bb pr list

Usage

bb --help lists every command, and bb <command> --help documents its flags. The shape is bb <noun> <verb>:

bb pr list                                # open PRs, with reviewers and approvals
bb pr view 42 --unresolved                # the PR plus comment threads still needing action
bb pr create main --title "Add caching"   # source branch inferred from your checkout
bb pr comment 42 -f src/auth.rs -l 88 -b "off by one"
bb branch list --user alice
bb update                                 # check for a newer release and update

bb update compares your version against the latest GitHub release. If Homebrew or cargo installed bb, it prints the right upgrade command for that package manager instead of overwriting a file they manage. For a standalone binary it verifies the download's checksum and replaces itself atomically.

One thing worth knowing that --help won't tell you:

Everything speaks JSON. Add --json to any command and pipe it to jq rather than parsing the tables, whose layout is not a contract. Scripts and agents should default to it.

bb pr list --json | jq -r '.[] | select(.approvals == []) | "\(.id)\t\(.title)"'

Shell completions make the rest discoverable:

bb completions zsh > ~/.zfunc/_bb         # also bash, fish, powershell, elvish

Use it from Claude Code

Copy this whole block into your project's CLAUDE.md so your agent drives PR review through bb instead of asking you to open a browser.

## Bitbucket via `bb`

This project uses Bitbucket, not GitHub. Use the `bb` CLI for all pull request work — never `gh`,
and never ask the user to open the web UI. Run `bb --help` to discover commands.

### Rules

- **Always pass `--json`** and parse that. Never scrape the human-readable tables; their layout is
  not a contract. The one exception is `pr diff`, where `--json` wraps the whole diff in an escaped
  JSON string — read that one as plain text.
- Never pass `-w`/`--web` — it tries to launch a browser.
- For multi-paragraph comment bodies use `--body-stdin` and pipe the text in. Interior blank lines
  and indentation are preserved; only trailing newlines are trimmed.
- Exit codes are meaningful: 0 success, 1 error, 2 not authenticated, 3 not found. Branch on those
  rather than matching error strings.
- Add `-R workspace/repo` to act on a repository that is not the current checkout.

### Reading review feedback

    bb pr list --json                        # find the PR
    bb pr view <id> --json                   # full PR plus general and inline comments
    bb pr view <id> --unresolved --json      # only threads still needing action
    bb pr diff <id>                          # raw diff
    bb pr files <id> --json                  # changed paths

Each entry under `.inline[]` has `file`, `line`, `author`, `body`, `resolved`, and `id`. Use that
`id` to reply in the right thread.

### Responding to review feedback

    # reply in the thread you are addressing
    bb pr comment <id> --reply-to <comment-id> --body "Fixed in <short-sha>."

    # raise a new point on a specific line
    bb pr comment <id> -f path/to/file.rs -l 88 --body "This drops the error."

    # multi-paragraph body
    printf 'Refactored as suggested.\n\nSplit the parser out.\n' | bb pr comment <id> --body-stdin

### Opening a PR

    bb pr create main --title "Short imperative summary"

Reference

Platform support

macOS (arm64, x86_64) and Linux (x86_64, aarch64), both covered by CI. Windows is not supported.

Contributing

Issues and pull requests are welcome. Before opening a PR, run cargo fmt --all --check, cargo clippy --all-targets -- -D warnings, and cargo test — CI enforces all three.

rust-toolchain.toml pins the exact toolchain used for those checks (currently 1.97), which rustup auto-installs on first use but which a contributor building offline needs to already have.

Security reports: please use GitHub's private vulnerability reporting rather than a public issue.

License

MIT — see LICENSE. This project is an independent Rust rewrite of the MIT-licensed PHP bb-cli; see NOTICE for attribution.