Bitbucket Data Center CLI (bb)

bb is a production-focused CLI for automating Bitbucket Data Center workflows. It combines scriptable machine output, safe dry-run planning, and behavior validated against a real Bitbucket server.

Data Center only — Bitbucket Cloud is not supported. Bitbucket Cloud (bitbucket.org) is a different API, and no bb command will work against it.

It is designed as the gh-style CLI experience for Bitbucket Data Center, including repository cloning and browser navigation ergonomics tailored to Bitbucket-hosted projects.

It ships an MCP server for AI agents too. Ask one about a pull request, and in a client that renders MCP Apps, such as Claude Desktop, VS Code or Goose, it answers with the pull request itself, right in the chat:

Views in your agent shows the overview, lists of pull requests, diffs and comment threads too.

Why teams adopt bb

• Operationally safe by default: dry-run planning for server mutations, and a confirmation before any command that deletes, removes, clears or revokes.
• Automation friendly: every --json payload arrives in the same envelope, for CI/CD and internal tooling; --yaml prints the same document as YAML.
• Spec-driven API interactions: client/server interactions are derived from Bitbucket Data Center's official OpenAPI spec.
• Git-native ergonomics: repository discovery from matching remotes to reduce repetitive --repo usage.
• Enterprise-ready auth model: token/basic auth with persisted server contexts and secure credential handling.
• Live-tested command behavior: command workflows are validated against a real Bitbucket Data Center server, not mocks alone.

What you can do with it

• Manage repositories, permissions, hooks, branches, tags, commits, and refs.
• Work with pull requests, comments, build statuses, and merge checks.
• Run project/admin operations and cross-repository search.
• Set permissions, webhooks, default tasks and branch restrictions once per project, where Bitbucket applies them to every repository.
• Clone repositories and open repository pages quickly (bb repo clone, bb browse).

Quick start

Install on Windows via WinGet:

winget install vriesdemichael.bb

Install on Windows via Scoop:

scoop bucket add vriesdemichael https://github.com/vriesdemichael/scoop
scoop install vriesdemichael/bb

Install on macOS or Linux via Homebrew:

brew install vriesdemichael/tap/bb

Install on Debian/Ubuntu or RHEL/Fedora from the release .deb/.rpm:

# Debian/Ubuntu
curl -LO "https://github.com/vriesdemichael/bitbucket-data-center-cli/releases/latest/download/bb_linux_amd64.deb"
sudo dpkg -i bb_linux_amd64.deb
# RHEL/Fedora
curl -LO "https://github.com/vriesdemichael/bitbucket-data-center-cli/releases/latest/download/bb_linux_amd64.rpm"
sudo rpm -i bb_linux_amd64.rpm

Install from Releases (Linux amd64 example):

curl -LO "https://github.com/vriesdemichael/bitbucket-data-center-cli/releases/latest/download/bb_linux_amd64.tar.gz"
curl -LO "https://github.com/vriesdemichael/bitbucket-data-center-cli/releases/latest/download/sha256sums.txt"
sha256sum -c sha256sums.txt --ignore-missing
tar -xzf bb_linux_amd64.tar.gz
install -m 0755 bb /usr/local/bin/bb

Every release also publishes the same files with the version in the name (bb_1.2.3_linux_amd64.tar.gz). Use those to pin a release; sha256sums.txt covers both spellings, so the checksum step above works either way.

Authenticate — store a token for your Bitbucket instance:

printf '%s' "$BITBUCKET_TOKEN" | bb auth login https://bitbucket.example.com --token-stdin
bb auth status

Target Bitbucket: https://bitbucket.example.com (auth=token, source=stored)
Credential storage: keyring

--token-stdin keeps the token out of the process list and your shell history. The token is stored in your OS keyring; where none is available the login fails unless you pass --allow-insecure-storage, which keeps it in the config file in plaintext.

Clone and browse — no need to look up URLs:

bb repo clone PLATFORM/api
bb browse --repo PLATFORM/api

Cloning into 'api'...
Cloned PLATFORM/api into api
# browse opens https://bitbucket.example.com/projects/PLATFORM/repos/api in your browser

Search — find repositories across all projects:

bb search repos --limit 20

PLATFORM/api      API Service
PLATFORM/backend  Backend Service
PLATFORM/web      Frontend Web App

Machine mode — stable JSON envelope for scripting and CI/CD:

bb --json auth status

{
  "data": {
    "ok": true,
    "bitbucketUrl": "https://bitbucket.example.com",
    "bitbucketVersionTarget": "",
    "authMode": "token",
    "authSource": "stored",
    "credentialStorage": "keyring",
    "checks": [
      { "name": "authentication", "ok": true, "advisory": false },
      { "name": "git credential helper", "ok": true, "advisory": true }
    ]
  },
  "meta": {
    "bbVersion": "..."
  }
}

ok is the one field a script needs: false when any non-advisory check failed. checks entries carry a detail and a remedy when they fail, omitted here for brevity. authSource is stored, env, or env/default when neither a stored nor an environment credential supplied one; bitbucketVersionTarget is empty unless an operator set BITBUCKET_VERSION_TARGET.

When something does not work, bb doctor reads every configuration file on its own and reports each problem with its line, needing no host and no network.

Ready for daily workflows? See the Developer Cheatsheet & Cookbook for scannable reference tables and top 10 daily developer recipes (PR reviews, local checkout, auto-merge, and IDE setup).

Docs

• Full docs site: https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/
• Developer Cheatsheet & Cookbook: docs/site/cheatsheet.md
• LLM guide (llms.txt): https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/llms.txt
• AI and llms.txt overview: docs/site/ai-and-llms.md
• Installation and Quickstart: docs/site/installation-and-quickstart.md
• Basic Usage: docs/site/basic-usage.md
• Troubleshooting: docs/site/troubleshooting.md
• Coming from gh: docs/site/gh-parity.md
• Advanced Topics: docs/site/advanced/index.md
• Command Reference (generated): docs/site/reference/commands/index.md
• ADR Index: docs/site/adr/index.md

Compatibility and contracts

• Supported versions: every Bitbucket Data Center release Atlassian supports. The newest is tested on every pull request, and the older ones are verified by hand against a real instance. A release keeps working after Atlassian's support for it ends. Bitbucket Versions says when each older release last passed and lists where one differs.
• API contract source: a version-pinned Atlassian OpenAPI artifact (docs/reference/atlassian/bitbucket-openapi.json). This fixes the endpoint and payload shapes the generated client is built from — it is the provenance of the spec, not a statement about which server versions work. Behavior is established by live tests, not the spec.
• CLI identity and machine contract: bb, with the envelope described in ADR-064
• JSON schemas: bb <command> --describe says what a command's output looks like, from the binary, as an outline or, under --json, as JSON Schema, and the configuration file and failure envelope schemas are published in docs and versioned with releases

For contributors

This README is an adopter-focused landing page.

• Start here: CONTRIBUTING.md — setup, the local gates, what CI checks, and how the live suite runs against a real Bitbucket
• Development workflows and project tasks: Taskfile.yml
• Decision records: docs/site/adr/
• Generated docs and docs tooling: docs/site/, tools/cli-docs-export/, tools/adr-index/

License and platform note

bb is licensed under the Apache License 2.0.

Atlassian Bitbucket Data Center is proprietary software. Use of local Docker images and server instances must comply with Atlassian licensing terms.