Skip to content

Installation and Quickstart

Which Bitbucket versions work

bb is tested against Bitbucket Data Center 10.4.3 on every pull request. A newer release is adopted once the suite passes against it.

Data Center only — Bitbucket Cloud is not supported

Bitbucket Cloud (bitbucket.org) is a different API, and no bb command will work against it. Installing bb for a bitbucket.org repository will not get you anywhere.

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

Download the .deb or .rpm for your architecture from GitHub Releases and install it:

# 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

To install a specific release rather than the newest, use the versioned name and a release tag: .../releases/download/v4.1.0/bb_4.1.0_linux_amd64.deb.

Install from release artifacts

  1. Download the platform archive, sha256sums.txt, and sha256sums.txt.sigstore.json from GitHub Releases.
  2. Verify the signed checksum manifest with Cosign, then verify checksums and run bb --help.

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"
curl -LO "https://github.com/vriesdemichael/bitbucket-data-center-cli/releases/latest/download/sha256sums.txt.sigstore.json"
cosign verify-blob \
    --bundle sha256sums.txt.sigstore.json \
    --certificate-identity "https://github.com/vriesdemichael/bitbucket-data-center-cli/.github/workflows/release.yml@refs/heads/main" \
    --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
    sha256sums.txt
sha256sum -c sha256sums.txt --ignore-missing
tar -xzf bb_linux_amd64.tar.gz
install -m 0755 bb /usr/local/bin/bb
bb --help

sha256sums.txt lists both the version-less and the versioned filename for every artifact, so --ignore-missing verifies whichever you downloaded. To pin a release, swap latest/download for download/v4.1.0 and use the versioned names.

Per-archive signatures, build provenance and SBOMs are covered in Release Verification.

Authenticate to Bitbucket

bb auth token-url --host https://bitbucket.acme.corp
printf '%s' "$BB_TOKEN" | bb auth login https://bitbucket.acme.corp --token-stdin
bb auth status

Secrets cannot be passed as flag values

There are no --token or --password flags: a flag value lands in the process argument list, where any local user can read it via ps or /proc/<pid>/cmdline, where Windows shows it in Task Manager details, and where process-auditing and EDR tooling records it -- and your shell keeps it in history. Use --token-stdin or --password-stdin, or set BITBUCKET_TOKEN.

Where credentials are stored

bb auth login stores the secret in your operating system's keyring — Credential Manager on Windows, Keychain on macOS, Secret Service on Linux.

Where no keyring is available — headless servers, most containers, WSL without gnome-keyring — bb falls back to writing the secret in plaintext into its config file (0600, in a 0700 directory) and warns on stderr. bb auth status reports which is in use:

bb auth status

Target Bitbucket: https://bitbucket.acme.corp (auth=token, source=stored)
Credential storage: keyring
- authentication: Alice Smith (alice)
- git credential helper: configured for https://bitbucket.acme.corp

bb auth status does not just report the configuration, it checks it: the authentication line proves the host is reachable, its certificate is trusted, any proxy is working, and the credential is still valid. A failing line says what to do about it.

Lines marked ! are advisory — worth knowing, but not a broken setup. The git credential helper is one: it is needed to git push and irrelevant if you only call the API, so it is reported and never fails the command.

In CI, --check makes it exit non-zero when a non-advisory check fails:

bb auth status --check

Without it the exit status stays zero whatever the findings, so existing scripts are unaffected. Under --json the exit status is always zero and the verdict is the ok field.

To refuse the plaintext fallback, pass --require-keyring at login, or set BB_REQUIRE_KEYRING=1 to enforce it fleet-wide. With the policy on, bb fails rather than degrading — including on later commands, if the config file already holds a plaintext credential from before the policy was set.

In CI and containers, prefer supplying BITBUCKET_TOKEN per invocation instead of logging in at all. An environment variable never touches the config file and satisfies BB_REQUIRE_KEYRING.

If your Bitbucket instance uses a different SSH clone host than its web/API URL, bb auth login will try to discover aliases automatically from the first accessible repository clone links. You can inspect or manage aliases explicitly with:

bb auth alias list --host https://bitbucket.acme.corp
bb auth alias discover --host https://bitbucket.acme.corp
bb auth alias add --host https://bitbucket.acme.corp git.acme.corp:7999

Let git authenticate too

bb auth login authenticates bb itself. Plain git — git push, git pull and git fetch inside a clone — does not go through bb, so it needs telling where to get credentials:

bb auth setup-git

Git now asks bb for a credential whenever it contacts your Bitbucket host, using what you just stored. No token is written into any repository, and revoking one takes effect immediately.

Run this once; it applies to every clone of that host. If you clone over SSH you do not need it — SSH authenticates with your key.

See Git Authentication for how it works and how to clean up clones made by older versions of bb.

When something is wrong

bb doctor is the first thing to run. It reads the stored, workspace and system configuration files each on its own and reports every problem in every one of them — an unparseable file, a misspelled key with its line, a key set in a file that never reads it — then shows where each effective setting comes from. It needs no host and no network, so it answers when nothing else does:

bb doctor

bb auth status is the other half: it proves the host is reachable, the certificate is trusted and the credential still works.

Troubleshooting has the messages people actually hit, each with what to do about it. Coming from gh maps the gh command you were about to type to its bb counterpart.

First useful commands

bb repo clone PLATFORM/api
bb browse --repo PLATFORM/api
bb search repos --limit 20
bb search prs --state OPEN
bb --json auth status

Runtime flags and environment variables

Most global runtime controls exist as both a flag and an environment variable — --ca-file / BB_CA_FILE, --retry-count / BB_RETRY_COUNT, and so on. Flags win over environment variables, which win over stored configuration.

Environment Variables is the complete list, with defaults and what each one does.

Behind a proxy, or against a certificate from an internal CA, see Networks, Proxies and TLS.

See Basic Usage for precedence, dry-run behavior, machine mode, and diagnostics guidance, and Troubleshooting when a command does not do what you expected.