Bitbucket Data Center CLI (bb)

bb is a production-focused CLI for automating Bitbucket Data Center workflows (targeting recent versions of Bitbucket for Data Center). It combines scriptable machine output, safe dry-run planning, and high-coverage live-behavior validation against real Bitbucket APIs.

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: stable JSON envelope contract (bb.machine, v2) 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 Arch Linux from the AUR:

yay -S bb-bin

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

VERSION=v1.0.0
# Debian/Ubuntu
curl -LO "https://github.com/vriesdemichael/bitbucket-data-center-cli/releases/download/${VERSION}/bb_${VERSION#v}_linux_amd64.deb"
sudo dpkg -i "bb_${VERSION#v}_linux_amd64.deb"
# RHEL/Fedora
curl -LO "https://github.com/vriesdemichael/bitbucket-data-center-cli/releases/download/${VERSION}/bb_${VERSION#v}_linux_amd64.rpm"
sudo rpm -i "bb_${VERSION#v}_linux_amd64.rpm"

Install from Releases (Linux amd64 example):

VERSION=v1.0.0
curl -LO "https://github.com/vriesdemichael/bitbucket-data-center-cli/releases/download/${VERSION}/bb_${VERSION#v}_linux_amd64.tar.gz"
curl -LO "https://github.com/vriesdemichael/bitbucket-data-center-cli/releases/download/${VERSION}/sha256sums.txt"
sha256sum -c sha256sums.txt --ignore-missing
tar -xzf "bb_${VERSION#v}_linux_amd64.tar.gz"
install -m 0755 bb /usr/local/bin/bb

Authenticate — store a token for your Bitbucket instance:

bb auth login --host https://bitbucket.acme.corp --token "$BB_TOKEN"
bb auth status

Target Bitbucket: https://bitbucket.acme.corp (auth=token, source=stored/default)

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

{
  "version": "v2",
  "data": {
    "bitbucket_url": "https://bitbucket.acme.corp",
    "bitbucket_version_target": "",
    "auth_mode": "token",
    "auth_source": "stored/default"
  },
  "meta": {
    "contract": "bb.machine"
  }
}

Docs

• Full docs site: https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/
• 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
• 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 image tag in docker/compose.yml, which is the one place it is recorded. Newer releases are adopted by bumping that image 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-9.4-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 / bb.machine v2
• JSON schemas for bulk policy/plan/status published in docs and versioned with releases

For contributors

This README is an adopter-focused landing page.

• 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

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