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

Command	Description
bb auth login	Authenticate with Bitbucket Cloud
bb auth logout	Remove stored credentials
bb auth status	Show authentication status

Repositories

Command	Description
bb repo list	List repositories in a workspace
bb repo view [slug]	View repository details
bb repo create	Create a new repository
bb repo clone <slug>	Clone a repository

Pull Requests

Command	Description
bb pr list	List pull requests
bb pr view <id>	View pull request details
bb pr create	Create a pull request
bb pr merge <id>	Merge a pull request
bb pr approve <id>	Approve a pull request
bb pr decline <id>	Decline a pull request
bb pr comment <id>	Add a comment
bb pr diff <id>	Show the diff
bb pr activity <id>	Show activity feed
bb pr status	Show status of relevant PRs
bb pr ready <id>	Mark draft PR as ready for review
bb pr draft <id>	Convert PR to draft
bb pr edit <id>	Edit title, description, or reviewers

Pipelines

Command	Description
bb pipeline list	List pipelines
bb pipeline view <uuid>	View pipeline details
bb pipeline run	Run a pipeline
bb pipeline stop <uuid>	Stop a running pipeline
bb pipeline logs <uuid>	View step logs (with --follow)

Search

Command	Description
bb search code <query>	Search for code across repositories

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

Variable	Description
BB_CLIENT_ID	Override OAuth consumer key
BB_CLIENT_SECRET	Override OAuth consumer secret
NO_COLOR	Disable color output

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