bb

bb — Bitbucket Cloud CLI

A fast, interactive command-line interface for Bitbucket Cloud. Manage repositories, pull requests, and pipelines without leaving your terminal.

Install

macOS note: Binary signing is in progress. For now, installs via Homebrew, mise, or binary download will require you to remove the quarantine attribute:

xattr -d com.apple.quarantine "$(which bb)"

The curl | sh and go install methods are not affected.

Homebrew

brew install tyrantkhan/tap/bb

mise

mise use -g ubi:tyrantkhan/bitbucket-cli[exe=bb]

Script

curl -sSL https://tyrantkhan.github.io/bitbucket-cli/install.sh | sh

Installs to ~/.local/bin. The script will let you know if it's not in your PATH and show you how to add it.

From source

go install github.com/tyrantkhan/bb@latest

Binary releases

Download from GitHub Releases.

Quick start

# Authenticate (interactive — choose OAuth or API token)
bb auth login

# List repos in your workspace
bb repo list

# View open pull requests
bb pr list

# Create a pull request from the current branch
bb pr create

# Run a pipeline
bb pipeline run

Authentication

Two methods are available:

OAuth (recommended) — opens your browser, no setup required:

bb auth login --web

API token — paste an Atlassian API token:

bb auth login --api-token

bb has no backend or servers. All requests go directly from your machine to the Bitbucket API. Your credentials are stored locally in ~/.config/bb/credentials.json and never leave your device.

Custom OAuth consumer

To use your own OAuth consumer instead of the built-in one, create one in Workspace settings → OAuth consumers with callback URL http://localhost/callback and the required permissions (Account Read, Repositories Read/Write, Pull Requests Read/Write, Pipelines Read/Write). Then:

export BB_CLIENT_ID="your-key"
export BB_CLIENT_SECRET="your-secret"
bb auth login --web

Run bb help oauth for full details.

Commands

Auth

Repositories

Pull Requests

Pipelines

Search

Smart defaults

bb detects context from your git repository:

• Workspace and repo are inferred from your git remote
• Source branch defaults to your current branch when creating PRs
• Destination branch defaults to main

You can always override with --workspace / --repo flags.

Output formats

# Default: colored table output
bb pr list

# JSON for scripting
bb pr list --format json

# Open in browser
bb pr view 42 --web

Configuration

Config is stored at ~/.config/bb/config.yml:

default_workspace: myworkspace
default_format: table

Environment variables

Shell completions

# Bash — add to ~/.bashrc
if command -v bb >/dev/null; then source <(bb completion bash); fi

# Zsh — add to ~/.zshrc
if command -v bb >/dev/null; then source <(bb completion zsh); fi

# Fish
bb completion fish > ~/.config/fish/completions/bb.fish

# PowerShell
bb completion pwsh > bb.ps1

AI skill

bb provides a skill file for AI coding assistants (Claude Code, Cursor, etc.) to learn bb's commands and help you with Bitbucket operations. Download it and add it to your project.

Full reference

bb reference

License

MIT