---
search:
  boost: 1.5
---

# Installation and Quickstart

## Which Bitbucket versions work

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

!!! warning "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

```powershell
winget install vriesdemichael.bb
```

## Install on Windows via Scoop

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

## Install on macOS or Linux via Homebrew

```bash
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:

```bash
# 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/[[ bb_version_tag ]]/bb_[[ bb_version ]]_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:

```bash
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/[[ bb_version_tag ]]` and use the
versioned names.

Per-archive signatures, build provenance and SBOMs are covered in
[Release Verification](advanced/enterprise-hardening.md#1-release-verification-pre-deployment).

## Authenticate to Bitbucket

```bash
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
```

!!! note "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:

```bash
bb auth status
```

```text
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:

```bash
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:

```bash
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:

```bash
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](advanced/git-authentication.md) 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:

```bash
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**](troubleshooting.md) has the messages people actually hit,
each with what to do about it. [Coming from `gh`](gh-parity.md) maps the `gh`
command you were about to type to its `bb` counterpart.

## First useful commands

```bash
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](reference/environment.md)** 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](advanced/networks-proxies-and-tls.md).

See [Basic Usage](basic-usage.md) for precedence, dry-run behavior, machine mode, and diagnostics guidance,
and [Troubleshooting](troubleshooting.md) when a command does not do what you expected.