bb — Bitbucket CLI

A gh-compatible CLI for Bitbucket Cloud. Single shell script, zero compilation, instant setup.

If you use GitHub's gh CLI and wish Bitbucket had the same thing — this is it.

Features

• Pull Requests — create, list, view, diff, comment, approve, merge, close, activity log
• Repos — list, view, clone
• Branches — list remote branches
• Search — repos by name, PRs by title
• CI/CD — view pipeline status for any PR
• URL parsing — pass Bitbucket PR URLs directly (bb pr view https://...)
• JSON output — --json flag on most commands for scripting
• AI-agent friendly — non-interactive flags, Claude Code skill included

Prerequisites

Tool	Install
zsh	Default shell on macOS; apt install zsh on Linux
curl	Ships with macOS; apt install curl on Linux
jq	brew install jq or apt install jq
python3	brew install python3 or comes with most systems
git	brew install git or Xcode CLT on macOS

Installation

git clone https://github.com/grohit1810/bb-cli.git
cd bb-cli
./install.sh

The installer will:

1. Check prerequisites
2. Add a source line to your ~/.zshrc pointing to this repo
3. Run bb setup if no credentials exist (interactive wizard)

To update later: cd bb-cli && git pull — changes take effect on next shell session.

Plugin Manager Installation

Works with any zsh plugin manager out of the box:

zinit:

zinit light grohit1810/bb-cli

sheldon (~/.config/sheldon/plugins.toml):

[plugins.bb-cli]
github = "grohit1810/bb-cli"

antidote (~/.zsh_plugins.txt):

grohit1810/bb-cli

oh-my-zsh (clone to custom plugins):

git clone https://github.com/grohit1810/bb-cli.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/bb-cli

Then add bb-cli to your plugins=(...) array in ~/.zshrc.

After loading via any plugin manager, run bb setup to configure credentials.

Manual Installation

If you prefer not to run the installer:

# Add to ~/.zshrc
source "/path/to/bb-cli/bb.sh"

# Create credentials
mkdir -p ~/.config/bb
cp credentials.example ~/.config/bb/credentials
# Edit ~/.config/bb/credentials with your values
chmod 600 ~/.config/bb/credentials

# Reload
source ~/.zshrc

Uninstall

cd bb-cli
./uninstall.sh

Setup

Run the interactive setup wizard:

bb setup

This will:

• Show you which Bitbucket App Password scopes are needed and which commands use them
• Prompt for your username, token, and workspace
• Verify the credentials work before saving
• Store credentials at ~/.config/bb/credentials (mode 600)

Run bb setup again anytime to change credentials.

Required App Password Scopes

Create an App Password at: https://bitbucket.org/account/settings/app-passwords/

Scope	Used by
read:pullrequest:bitbucket	pr list, pr view, pr diff, pr checks, pr status, pr activity
read:repository:bitbucket	repo list, repo view, repo clone, branch list, browse
read:workspace:bitbucket	repo list, search repos
read:user:bitbucket	pr status (finding your PRs)
read:me	auth status, pr status
read:pipeline:bitbucket	pr checks
write:pullrequest:bitbucket	pr create, pr edit, pr comment, pr approve, pr merge, pr close
write:repository:bitbucket	Reserved for future repo write operations
write:pipeline:bitbucket	Reserved for future pipeline triggers

Usage

bb help                          # Full command reference

# Pull requests
bb pr list                       # List open PRs
bb pr view 123                   # View PR details
bb pr view 123 -c                # With comments
bb pr view 123 -w                # Open in browser
bb pr diff 123                   # Full diff
bb pr checks 123                 # Pipeline status
bb pr status                     # Your PRs + review requests
bb pr activity 123               # Full timeline
bb pr checkout 123               # Fetch + switch to PR branch

bb pr create -t "My PR" -b main  # Create PR from current branch
bb pr comment 123 -m "LGTM"     # Add comment
bb pr approve 123                # Approve
bb pr merge 123 --squash --yes   # Merge with squash
bb pr close 123 --yes            # Decline (permanent!)

# Repos
bb repo list                     # All workspace repos
bb repo view                     # Current repo info
bb repo view myrepo --json       # Specific repo, JSON output
bb repo clone myrepo             # Clone via SSH

# Branches
bb branch list                   # Remote branches

# Search
bb search repos myservice        # Search repos by name
bb search prs "bug fix"          # Search PRs by title

# Utilities
bb browse                        # Print current branch URL
bb browse --web                  # Open in browser
bb api GET /user                 # Raw API call

URL Parsing

Pass Bitbucket URLs directly — no need to extract workspace/repo/id manually:

bb pr view https://bitbucket.org/myworkspace/myrepo/pull-requests/456

JSON Output

Most read commands support --json for scripting:

bb pr list --json | jq '.[].title'
bb pr view 123 --json | jq '.state'
bb repo list --json -L 10 | jq '.[].slug'

Using with Claude Code

Install the skill

Copy the skill file to your Claude Code skills directory:

cp skills/bb-cli.md ~/.claude/skills/bb-cli.md

This teaches Claude Code the full command reference, safe vs. write operation boundaries, and common workflows.

Write operation guardrail

The skill enforces that AI agents never execute write operations (pr create, pr merge, pr comment, etc.) without explicit user approval. Read operations are always safe.

Configuration

Variable	Default	Description
BB_CREDENTIALS_FILE	~/.config/bb/credentials	Path to credentials file
_BB_CURL	auto-detected	Path to curl binary
_BB_JQ	auto-detected	Path to jq binary
_BB_PY	auto-detected	Path to python3 binary

Running Tests

The test suite only exercises read-only commands — safe to run anytime:

export TEST_REPO_DIR=/path/to/a/bitbucket/repo
export TEST_PR_ID=123
export TEST_SEARCH_QUERY=reponame
export TEST_PR_SEARCH=keyword
export TEST_EXPLICIT_SLUG=reponame
zsh tests/test_bb.sh

Contributing

1. Fork and clone
2. Make changes to bb.sh
3. Update skills/bb-cli.md if adding/changing commands
4. Run the test suite
5. Submit a PR

License

MIT