Open Source · Written in Go · MIT License

Bitbucket Cloud,
from your terminal.

Manage repositories, pull requests, pipelines, issues, and more — all without leaving the command line.

Get Started View on GitHub
$ brew install PhilipKram/tap/bb
0
Commands
Go
Written In
0
Command Groups
MIT
License
Why bb

Everything Bitbucket, one command away

A powerful CLI that brings the full Bitbucket Cloud workflow to your terminal with a familiar, intuitive interface.

Pull Requests

Create, review, approve, merge, and comment on PRs. Add inline comments on specific files and lines. View diffs and activity logs.

bb pr create --title "Feature" --reviewer @bob

Issues

Full issue lifecycle management. Create, edit, vote, watch, comment, and delete issues from the command line.

bb issue list --state open

CI/CD Pipelines

Trigger pipelines, view step logs, stop running builds, and watch pipeline status in real-time from your terminal.

bb pipeline trigger --branch main

Repositories

List, create, fork, clone, and delete repositories. Browse commits and view diffs across branches.

bb repo clone workspace/repo

Branches & Tags

Create and delete branches, manage tags, and view branch restrictions. Full branch lifecycle management.

bb branch list workspace/repo

OAuth 2.0 Auth

Login via browser OAuth or app passwords. Tokens auto-refresh when expired. Credentials stored securely via XDG conventions.

bb auth login

Flexible Output

Human-readable tables by default, JSON output for scripting. Pipe results into jq, awk, or any tool you like.

bb pr list --json

MCP Server

Built-in Model Context Protocol server with per-user OAuth, stdio and HTTP transports. Deploy as a shared Docker service — each user authenticates with their own Bitbucket account.

bb mcp serve --transport http

Shell Completion

Tab completion for Bash, Zsh, Fish, and PowerShell. Dynamic suggestions for workspaces, repositories, branches, and PR numbers.

bb completion zsh
Installation

Get started in seconds

Multiple installation methods to fit your workflow. Pick whichever suits you best.

Quick Install

terminal 
curl -fsSL https://raw.githubusercontent.com/PhilipKram/Bitbucket-CLI/main/install.sh | sh

Homebrew

terminal 
brew install PhilipKram/tap/bb

Go Install

terminal 
# Requires Go 1.22+
go install github.com/PhilipKram/bitbucket-cli@latest

Pre-built Binary

Download pre-built binaries for Linux, macOS, and Windows from the releases page.

Available for amd64 and arm64.

Authentication

Authenticate with Bitbucket Cloud. OAuth is the default — just run bb auth login and it opens your browser.

OAuth Login (Default)

The CLI starts a local server, opens your browser for authorization, and exchanges the code for a token using PKCE — no client secret needed.

  • Browser-based OAuth 2.0 with PKCE
  • App password support for CI/CD
  • Auto-refreshes expired tokens
  • XDG-compliant credential storage
terminal 
# OAuth login (default) — opens your browser
bb auth login

# Check current auth status
bb auth status

# Print stored token
bb auth token

# Refresh an expired token
bb auth refresh

# Logout
bb auth logout
Command Reference

Every command at your fingertips

Comprehensive coverage of Bitbucket Cloud features organized into intuitive command groups.

Authentication
bb auth loginOAuth login (opens browser)
bb auth logoutRemove stored credentials
bb auth statusView auth status
bb auth tokenPrint stored auth token
bb auth refreshRefresh OAuth access token
Repositories
bb repo listList repositories
bb repo viewView repository details
bb repo create <name>Create a new repository
bb repo clone <repo>Clone a repository
bb repo fork <repo>Fork a repository
bb repo delete <repo>Delete a repository
bb repo commitsList recent commits
bb repo diffView a diff
Pull Requests
bb pr createCreate a pull request
bb pr listList pull requests
bb pr view <id>View PR details
bb pr merge <id>Merge a pull request
bb pr approve <id>Approve a pull request
bb pr unapprove <id>Remove approval
bb pr decline <id>Decline a pull request
bb pr diff <id>View the diff
bb pr comment <id>Add a comment (inline supported)
bb pr comments <id>List comments
bb pr activity <id>View activity log
bb pr edit <id>Edit PR properties
Issues
bb issue createCreate a new issue
bb issue listList issues
bb issue view <id>View issue details
bb issue edit <id>Edit an issue
bb issue delete <id>Delete an issue
bb issue comment <id>Add a comment
bb issue comments <id>List comments
bb issue vote <id>Vote on an issue
bb issue watch <id>Watch an issue
CI/CD Pipelines
bb pipeline listList pipelines
bb pipeline view <id>View pipeline details
bb pipeline triggerTrigger a new pipeline
bb pipeline stop <id>Stop running pipeline
bb pipeline steps <id>List pipeline steps
bb pipeline log <id>View step log output
bb pipeline watch <id>Watch pipeline status
Branches & Tags
bb branch listList branches
bb branch create <name>Create a branch
bb branch delete <name>Delete a branch
bb branch tagsList tags
bb branch tag-createCreate a tag
bb branch tag-deleteDelete a tag
bb branch restrictionsList branch restrictions
Workspaces & Users
bb workspace listList workspaces
bb workspace viewView workspace details
bb workspace membersList members
bb workspace projectsList projects
bb workspace permissionsList permissions
bb user meShow current user
bb user view <user>View a user profile
bb user ssh-keysList SSH keys
Snippets, Config & More
bb snippet listList snippets
bb snippet createCreate a snippet
bb snippet view <id>View a snippet
bb config viewShow configuration
bb config set-default-workspaceSet default workspace
bb completion <shell>Generate shell completions
bb mcp serveStart MCP server (stdio or HTTP)
bb mcp installRegister bb in an AI client
bb mcp uninstallRemove bb from an AI client
bb mcp statusCheck MCP registration status
bb upgradeUpgrade bb to latest

Repository Argument: Most commands accept a workspace/repo-slug positional argument. When omitted, bb auto-detects the repository from the current git remote. Use --json on any list command for machine-readable output.

Examples

Real-world workflows

Common patterns for day-to-day Bitbucket usage, straight from the terminal.

Complete PR Workflow

Create, review, comment on, and merge a pull request — all without leaving the terminal.

  • Create PRs with auto-fetched default reviewers
  • Add inline comments on specific files and lines
  • View diffs and activity logs
  • Approve and merge with a single command
terminal 
# Create a pull request from current branch
bb pr create --title "Add user authentication" \
  --description "Implements OAuth2 login flow" \
  --reviewer @bob

# List open PRs
bb pr list --state OPEN

# View PR details and diff
bb pr view 42
bb pr diff 42

# Leave an inline comment on the diff
bb pr comment 42 --body "Consider refactoring this" \
  --file "src/auth.go" --line 57

# Approve and merge
bb pr approve 42
bb pr merge 42

CI/CD Pipeline Monitoring

Trigger, monitor, and debug CI/CD pipelines without opening the Bitbucket web UI.

  • Trigger pipelines on any branch
  • Watch pipeline status in real-time
  • Debug failed steps with log output
terminal
# Trigger a pipeline on main
bb pipeline trigger --branch main

# List recent pipelines
bb pipeline list

# Watch pipeline progress in real-time
bb pipeline watch 187

# Debug a failed step
bb pipeline steps 187
bb pipeline log 187 --step 3

# Stop a running pipeline
bb pipeline stop 187

Issue Tracking

Manage bugs, features, and tasks from the command line — create, edit, comment, and close issues.

  • Create issues with priorities
  • Filter issues by state
  • Vote and watch issues
terminal
# Create a bug report
bb issue create --title "Login page broken on Safari" \
  --kind bug --priority critical

# List open issues
bb issue list --state open

# Add a comment and vote
bb issue comment 42 --body "Fixed in PR #99"
bb issue vote 42

# Edit and close
bb issue edit 42 --state resolved

Advanced Usage

Work with workspaces, manage branches, JSON output for scripting, and AI agent integration.

  • Target any workspace/repo
  • JSON output for scripting
  • Branch and tag management
  • MCP server with per-user OAuth & Docker
terminal
# Target a specific workspace/repo
bb pr list myteam/backend-api
bb repo view myteam/frontend

# JSON output for scripting
bb pr list --json | jq '.[].title'

# Branch management
bb branch create feature/auth --target main
bb branch tags myteam/backend-api

# MCP server with per-user OAuth (team deployment)
bb mcp serve --transport http --client-id KEY --client-secret SECRET
claude mcp add --transport http bitbucket http://localhost:8080/mcp

# Self-update to latest version
bb upgrade
Configuration

Fully customizable

Configuration stored in ~/.config/bb/ following XDG conventions.

Config Commands

CommandDescription
bb config viewShow current configuration
bb config set-default-workspaceSet your default workspace
bb config set-formatSet output format (table/json)

Token Storage

FileDescription
token.jsonOAuth access & refresh tokens
config.jsonDefault workspace & preferences

Shell Completions

ShellSetup
Bashsource <(bb completion bash)
Zshsource <(bb completion zsh)
Fishbb completion fish | source
PowerShellbb completion powershell | Out-String | Invoke-Expression