bb-tool 1.0.1

Bitbucket Cloud CLI for PR review workflows

bb

gh for GitHub. bb for Bitbucket. The missing command-line tool for Bitbucket Cloud pull requests.

Why bb?

GitHub has gh. GitLab has glab. Bitbucket Cloud has nothing — until now.

If you use Bitbucket at work, you know the pain: context-switch to the browser to check PRs, post review comments, merge branches. bb lets you do all of that from the terminal, in the repo you're already working in.

• Zero config — auto-detects workspace and repo from your git remote
• Full PR lifecycle — list, create, review, comment, approve, merge
• Inline code comments — comment on specific files and lines
• Threaded discussions — reply to and resolve comment threads
• JSON output — pipe to jq for scripting and automation
• AI-ready — ships with a Claude Code skill for AI-assisted PR reviews

Quick Start

pip install bb-tool
bb setup        # authenticates + installs Claude Code skill
bb pr list

That's it. bb setup walks you through creating an API token (opens your browser), then installs the Claude Code skill. If you're in a Bitbucket repo, bb auto-detects your workspace and repo.

60-second workflow: review a PR from your terminal

# See what's open
bb pr list

# Pick a PR and get the overview
bb pr show 42
bb pr files 42

# Read the diff
bb pr diff 42

# Leave a comment on a specific line
bb pr comment 42 --body "This should use a context manager" --file src/db.py --line 15

# Approve and merge
bb pr approve 42
bb pr merge 42 --strategy squash --close-source

Installation

# pip
pip install bb-tool

# pipx (isolated install, recommended)
pipx install bb-tool

# uv
uv tool install bb-tool

Requires Python 3.10+.

Authentication

bb uses Atlassian API tokens for authentication. Create a token with the following scopes:

Read: read:me, read:pullrequest:bitbucket, read:repository:bitbucket, read:project:bitbucket, read:user:bitbucket

Write: write:pullrequest:bitbucket

bb auth login    # Opens browser to create a token, then prompts for credentials
bb auth status   # Verify credentials
bb auth logout   # Clear stored credentials

Credentials are stored in your system keyring. If keyring is unavailable, they fall back to ~/.config/bb/tokens.json (file mode 600).

Configuration

In most cases, you don't need any configuration — bb reads your git remote.

Config file (optional)

Create ~/.config/bb/config.toml to set defaults:

[defaults]
workspace = "myworkspace"
repo = "myrepo"
dest_branch = "main"

Environment variables

Override anything with env vars (highest priority):

• BITBUCKET_WORKSPACE — workspace slug
• BITBUCKET_REPO — repository slug
• BITBUCKET_DEST_BRANCH — default destination branch for pr create

Resolution order: env vars > config file > git remote

Commands

Pull Requests

bb pr list                              # List open PRs
bb pr list --state MERGED --limit 10    # Filter and limit
bb pr list --json                       # JSON output (pipe to jq)

bb pr show 42                           # PR details
bb pr show 42 --json                    # JSON output
bb pr files 42                          # Changed files with line counts
bb pr diff 42                           # Full unified diff

bb pr create -t "Add feature X"        # Create from current branch
bb pr create -t "Fix" -s feat -d main  # Explicit branches
bb pr create -t "Update" --body "..."  # With description
bb pr create -t "Fix" --reviewer alice # Add reviewers

bb pr approve 42                        # Approve a PR
bb pr merge 42                          # Merge a PR
bb pr merge 42 --strategy squash       # Squash merge
bb pr merge 42 --close-source          # Delete source branch after merge

Comments

bb pr comments 42                                           # List all (threaded)
bb pr comment 42 --body "Looks good"                        # General comment
bb pr comment 42 --body "Nit" --file src/main.py --line 15  # Inline comment
bb pr reply 42 --comment-id 123 --body "Fixed"              # Reply to thread
bb pr resolve 42 --comment-id 123                           # Resolve thread

Workspace/Repo Override

All pr subcommands accept -w and -r flags:

bb pr -w myteam -r backend list
bb pr -w myteam -r backend show 99

Claude Code Integration

bb ships with a Claude Code skill for AI-assisted PR review workflows:

bb setup-skill   # installs to ~/.claude/skills/bb/

This is included automatically when you run bb setup. Once installed, Claude can list PRs, read diffs, post review comments, and manage threads on your behalf.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT