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.

Why teams adopt bb

• Operationally safe by default: dry-run planning for server mutations and explicit bulk plan/apply workflows.
• Automation friendly: every --json payload arrives in the same envelope, for CI/CD and internal tooling.
• 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.
• Apply policy-driven multi-repository changes via bulk plan/review/apply workflows.
• 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' "$BB_TOKEN" | bb auth login https://bitbucket.acme.corp --token-stdin
bb auth status

Target Bitbucket: https://bitbucket.acme.corp (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 bb falls back to the config file in plaintext and says so — pass --require-keyring to fail instead.

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.acme.corp/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.acme.corp",
    "bitbucketVersionTarget": "",
    "authMode": "token",
    "authSource": "stored",
    "credentialStorage": "keyring",
    "checks": [
      { "name": "authentication", "ok": true, "advisory": false },
      { "name": "git credential helper", "ok": true, "advisory": true }
    ]
  },
  "meta": {
    "bbVersion": "v4.0.0"
  }
}

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 version: the newest Bitbucket Data Center release that runs in the project's container stack and passes the live integration suite. There is no pinned target advertised here — the version under test is the base image tag in docker/harness/Dockerfile, which is the one place it is recorded. Newer releases are adopted by bumping that tag when they work; some do not run in the stack, so the newest published release is not automatically the supported one. Set BITBUCKET_VERSION_TARGET if you want to record a version for your own environment.
• 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 for bulk policy/plan/status 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/decisions/
• Generated docs and docs tooling: docs/site/, tools/cli-docs-export/, tools/adr-markdown-export/

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.