bb vriesdemichael

Use this command to install bb with WinGet:

winget install --id=vriesdemichael.bb -e

Bitbucket server (not cloud) command line tool. The 'gh' of bitbucket server.

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:

# 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

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

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:
Developer Cheatsheet & Cookbook: docs/site/cheatsheet.md
LLM guide (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 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 / 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.

Bitbucket Data Center CLI (`bb`)

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:

# 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

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

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"
  }
}

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:
Developer Cheatsheet & Cookbook: docs/site/cheatsheet.md
LLM guide (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 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 / 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.

bb vriesdemichael

README

Bitbucket Data Center CLI (bb)

Why teams adopt bb

What you can do with it

Quick start

Docs

Compatibility and contracts

For contributors

License and platform note

bb vriesdemichael

README

Bitbucket Data Center CLI (bb)

Why teams adopt bb

What you can do with it

Quick start

Docs

Compatibility and contracts

For contributors

License and platform note

Bitbucket Data Center CLI (`bb`)

Why teams adopt `bb`

Bitbucket Data Center CLI (`bb`)

Why teams adopt `bb`