Bitbucket CLI

Fast, scriptable CLI for Bitbucket Cloud

Inspired by GitHub's gh CLI - the same great experience for Bitbucket

_{Docs · Quick Start · Command Reference · Issues}

_{Note: This is an unofficial, community-maintained CLI tool.
It is not affiliated with or endorsed by Atlassian or Bitbucket.}

---

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.