lite-bb

lite-bb (Lite Bitbucket CLI)

Because sometimes you want gh, but your company uses Bitbucket.

lite-bb is a lightweight, gh-style command-line tool for managing Bitbucket repositories and pull requests. It brings the simplicity and ergonomics of the GitHub CLI to Bitbucket — whether you're on Bitbucket Cloud or running Bitbucket Server / Data Center on-prem.

Built for developers who live in the terminal, CI/CD pipelines that need scriptable PR workflows, and LLM agents that benefit from structured --json output.

Features

• Familiar interface — if you know gh pr, you already know bb pr. Same commands, same flags, same muscle memory.
• Cloud + on-prem — works with both Bitbucket Cloud and Bitbucket Server / Data Center. Auto-detects your instance type from the git remote.
• Zero-config start — auto-detects workspace, repo, and branch from your git context. Just cd into your repo and go.
• Repository management — bb repo list/view/clone/create manages repos the same way gh repo does.
• API passthrough — bb api <endpoint> makes authenticated API calls like gh api, with --jq, --field, and --method support.
• Code search — bb search code searches across your workspace or a specific repo, with filters for extension and filename.
• Machine-readable output — every command supports --json for scripting, piping, and LLM agent consumption.
• Credential verification — bb auth login validates your token against the API before saving, so you catch auth issues immediately.
• Easy install — distributed as a pre-built binary via PyPI. No Rust toolchain needed — just pip install lite-bb.

Claude Code Plugin

lite-bb ships a Claude Code skill that teaches Claude to use bb instead of gh when working with Bitbucket repos. It covers the full CLI surface — auth, PRs, code review, repos, search, and raw API access.

/plugin marketplace add https://github.com/key4ng/lite-bb
/plugin install lite-bb

Install

The recommended way to install lite-bb is via pip or uv. This downloads a pre-built native binary for your platform — no Rust toolchain required.

pip install lite-bb
# or
uv pip install lite-bb

After installation, the bb command is available on your PATH.

cargo install --path crates/cli

Quick Start

# 1. Authenticate (interactive — choose Cloud or Server, enter token)
bb auth login

# 2. List your repos
bb repo list

# 3. Clone a repo
bb repo clone myworkspace/my-repo

# 4. List open PRs in the current repo
bb pr list

# 5. Create a PR from your current branch
bb pr create --title "feat: add user authentication"

# 6. View PR details (human-readable or JSON)
bb pr view 42
bb pr view 42 --json

Authentication

lite-bb supports two authentication methods, matching how Bitbucket handles access:

• Access Token — a single token value (workspace, project, or repository token). This is the simplest option, similar to gh auth login with a personal access token.
• App Password — a username + app password pair. Useful when your organization requires app passwords for API access.

Interactive Login

bb auth login

This walks you through an interactive setup:

1. Choose your Bitbucket instance — Cloud or Server / Data Center
2. For Server/DC, enter the server URL (auto-detected from your git remote if available)
3. Choose your credential type — Access Token or App Password
4. Enter your credentials
5. Credentials are verified against the API before saving

# Check your current auth status
bb auth status

# Remove saved credentials
bb auth logout

Environment Variables

For CI/CD pipelines and scripting, you can set credentials via environment variables. These take priority over the config file.

The config file is stored at ~/.config/bb/config.yml and respects the XDG_CONFIG_HOME environment variable.

Usage

All commands auto-detect the workspace and repository from your git remote. You can override this with -R WORKSPACE/REPO (or -R PROJECT/REPO for Server/DC).

Repositories

# List repos in your workspace
bb repo list

# List with visibility filter
bb repo list --visibility private

# View a repo
bb repo view myworkspace/my-repo