At a glance

• Stay in the terminal for repo, PR, and snippet workflows
• JSON output for scripting and automation
• Auto-detects workspace and repo from your git directory

Install

Requires: Bun runtime 1.0 or higher. The CLI is installed via npm but runs on the Bun runtime — Node.js is not supported.

1. Install Bun (if bun --version fails):

   curl -fsSL https://bun.sh/install | bash

2. Install the CLI:

   npm install -g @pilatos/bitbucket-cli
   bb --version

3. Tab completion (optional, recommended):

   bb completion install

   Then restart your shell.

Quick Start

bb auth login
bb repo clone myworkspace/myrepo
bb pr list

Common Commands

bb repo list
bb pr create --title "Add feature"
bb pr approve 42
bb browse 42                  # open PR #42 in your browser
bb browse src/cli.ts:20       # open a file at a specific line
bb api /user                  # call any Bitbucket API endpoint (escape hatch)
bb config set defaultWorkspace myworkspace

Global options (work on every command): --json [fields], --jq, --no-color, --no-unicode, --no-truncate, --limit, --all, --locale, -w, --workspace, -r, --repo. Full reference: Global Flags.

Scripting with --json and --jq

--json accepts an optional comma-separated field list to project the output, and --jq filters the JSON in-process (no external jq binary required):

# Project to specific fields
bb pr list --json id,title,state

# Filter through built-in jq
bb pr list --json --jq '.pullRequests[] | select(.state == "OPEN") | .title'

See JSON Output and the Scripting guide for more.

Docs

Full documentation: bitbucket-cli.paulvanderlei.com

• Quick Start Guide
• Command Reference
• Guides (Scripting, CI/CD)
• AI assistant integration (Claude Code, Cursor, Windsurf): see Guides > AI Agents
• Changelog — what's new in recent releases
• Help (Troubleshooting, FAQ)

Authentication

• Create a token: Bitbucket API Tokens
• Authenticate: bb auth login

Note: Bitbucket app passwords are deprecated (new ones can no longer be created). Use OAuth or API tokens instead.

Environment Variables

| Variable | Description | | --------------- | ---------------------------------------------------------------------- | | BB_USERNAME | Bitbucket username (fallback for bb auth login) | | BB_API_TOKEN | Bitbucket API token (fallback for bb auth login; for CI) | | BB_WORKSPACE | Default workspace; overrides defaultWorkspace config | | BB_LOCALE | BCP-47 locale for date/time formatting (e.g. de-DE); --locale wins | | BB_NO_UNICODE | Use ASCII fallbacks for symbols when set (any non-empty value) | | DEBUG | Enable HTTP debug logging — must equal exactly true | | NO_COLOR | Disable color output when set | | FORCE_COLOR | Force color output when set (and not 0) |

Full reference: Environment variables.

Contributing

Read the Contributing Guide to get started.

Acknowledgments

• Inspired by GitHub CLI (gh)
• Built with Commander.js
• Uses the Bitbucket Cloud REST API

License

MIT License - see LICENSE for details.