# Bitbucket Data Center CLI

`bb` is the operational CLI for Bitbucket Data Center. It is the
high-signal command surface for working with self-hosted Bitbucket — pull requests,
repositories, branches, tags, commits, build status, and project-wide settings — without
scraping web pages or inventing API calls. It is not the CLI for Bitbucket Cloud.

This file is a setup guide. If you are an agent, work through it in order: install,
authenticate, then enable either the skill or the MCP server. The last section describes
the machine-readable output contract you will be parsing.

## 1. Install

`bb` ships as a single binary. Use whichever package manager is present:

```bash
brew install vriesdemichael/tap/bb
```

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

Debian, Ubuntu, RHEL and Fedora packages, platform archives, and Sigstore verification
instructions are on the installation page linked at the end.

Confirm the binary is present and note its version — the skill and the command surface are
version-specific:

```bash
bb --version
```

## 2. Authenticate

`bb` authenticates with a personal access token. There is no OAuth flow: Bitbucket Data
Center ships with no configured OAuth clients and non-admin users cannot create them, so
token auth is the supported path. Ask the user for a PAT rather than trying to
provision one yourself.

Pass the token on stdin. A secret passed as a flag value appears in the process argument
list, where any local user can read it, and the shell records it in history:

```bash
printf '%s' "$BITBUCKET_TOKEN" | bb auth login https://bitbucket.example.com --token-stdin
```

If the user does not have a token yet, print the host-specific creation URL for them:

```bash
bb auth token-url --host https://bitbucket.example.com
```

Verify the result. `bb auth status` reports the resolved host, how the credential is
stored, and whether it still authenticates. Add `--check` to make a failing check a
non-zero exit, which is what you want when you are deciding whether to continue:

```bash
bb auth status --check
```

Credentials go to the OS keyring. On headless servers and most containers there is no
keyring, and `bb auth login` fails there unless it is given `--allow-insecure-storage`,
which keeps the secret in the config file in plaintext. Setting `BITBUCKET_TOKEN` for the
run instead needs neither.

When a command refuses and the configuration is the suspect, `bb doctor` reads every
configuration file on its own and reports each problem with its line, plus where every
effective setting comes from. It needs no host and no network:

```bash
bb doctor --json
```

## 3. Enable the skill

The skill teaches a shell-driving agent the command surface. `bb` carries it embedded, so
installing it needs no network:

```bash
bb ai skill install
```

That writes `.agents/skills/bb/SKILL.md`, and `.claude/skills/bb/SKILL.md` for Claude Code,
which reads only its own directory — project scope. For user scope:

```bash
bb ai skill install --global
```

If the agent expects a different path, print the skill and redirect it:

```bash
bb ai skill show > .agents/skills/bb/SKILL.md
```

When `bb` is not installed yet, the baseline skill is also published through the open
agent skills ecosystem:

```bash
npx skills add vriesdemichael/bitbucket-data-center-cli
```

Prefer `bb ai skill show` or `bb ai skill install` where you can. Those print the skill
embedded in the running binary, so it always matches the `bb` you are about to invoke. The
npx copy is a snapshot taken from the repository at release time and can describe a
different version than the one installed (ADR-040). Re-run `bb ai skill install` after
upgrading `bb`.

## 4. Or enable the MCP server

The MCP server exposes Bitbucket operations as typed tools over stdio, for clients that
speak MCP natively rather than driving a shell:

```bash
bb ai mcp serve --project PLAT
```

Configure it as a stdio server — command `bb`, args `["ai", "mcp", "serve", "--project", "PLAT"]`.
It is not an HTTP server and there is no port to connect to.

**Ask the person before you configure it.** How far the server lets an agent go is theirs to
choose, not yours. Ask them, and write the entry with what they answer:

- whether the agent may change Bitbucket (`--allow-writes`), or only read, the default;
- which project or repository to confine it to (`--project`, `--repo`);
- whether it should run on a token of its own with fewer rights than theirs, such as a
  read-only one: log it in to a configuration file of its own and name that file with
  `BB_CONFIG_PATH` in the entry, which keeps the secret out of the client's file;
- whether the tools that decide a merge should ask them in the client first
  (`--elicitation-opt-in`);
- whether to offer only some tools (`--tools`) or leave some out (`--exclude`);
- whether to keep an audit trail of every call (`--audit-file`);
- whether their organisation allows the line bb adds to what an agent writes, saying an AI
  agent wrote it (`--ai-disclosure=false` turns it off, and with it the tools that would
  publish the agent's text under their name at once).

Then tell them what the entry allows.

Things worth knowing before you wire it up:

- Confine it with `--project` or `--repo` to where the agent works. Unconfined, it reaches every
  repository the token can read, and an agent misled by what it reads can copy a file from one
  of them into a pull request others read.
- `--host` is required when more than one Bitbucket instance is configured; the server
  exits immediately if it is missing (ADR-039).
- The server offers only the tools that read unless `--allow-writes` lets it make changes
  in Bitbucket, and the MCP client decides whether a call runs: nothing asks by default. With `--elicitation-opt-in`, the ones that change whether or when a pull
  request merges, and creating a tag, ask the person to confirm each call in the client;
  a client that cannot show that confirmation gets error -32021 for them (ADR-103).
  `bb ai mcp tools` lists every tool with whether it writes and whether it asks.
- `--tools` is an allowlist and `--exclude` a denylist, for narrowing the surface further;
  neither brings back a tool a read-only server withholds.
- `--project` and `--repo` confine the server to one workspace; a call aimed elsewhere is
  refused, and tools that address something Bitbucket does not scope to a project are
  withheld entirely (ADR-062).
- `--audit-file` records every tool call as JSON Lines, to a path or to `stderr`. It is off
  by default (ADR-062).
- Every tool declares an output schema and the SDK validates results against it, so a
  handler cannot return a shape its schema does not describe (ADR-061).

The audit trail covers this server only. An agent that can also run shell commands can
invoke `bb` directly and bypass it. The control that survives that is the token the
server runs under -- a read-only PAT logged in to a configuration file of its own, named
with `BB_CONFIG_PATH` in the client's `env` block -- which binds at the Bitbucket server.
[Set Up the MCP Server in Your Client](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/how-to/mcp-clients/)
has the entry for Claude Code, Claude Desktop, Cursor and VS Code.

## 5. Which one to enable

- **The skill**, if you drive a shell. You already have `bb`; the skill tells you how to
  use it, and you get the full command surface rather than a curated tool set.
- **The MCP server**, if your client is MCP-native and you would rather call typed tools
  than parse a terminal. You also get the workspace confinement and audit trail described
  above, which have no equivalent on the shell path.

Both at once is redundant, not additive. Pick the one that matches how you invoke things.

## 6. The machine contract

Pass `--json` whenever another system parses the output. Every command that supports it
emits a single bb.machine envelope on stdout (`--yaml` emits the same document as YAML):

```json
{"data": {}, "meta": {"bbVersion": "v6.1.0"}}
```

There is no envelope version field. The release version is the compatibility
signal, and `meta.bbVersion` reports the binary that produced the document.

A failure replaces `data` with `error`, carrying a `kind` from a fixed taxonomy
(`authentication`, `authorization`, `validation`, `not_found`, `conflict`, `transient`,
`permanent`, `not_implemented`, `cancelled`, `unknown_outcome`, `unsupported`,
`internal`), a `message`, and the `exitCode` that matches the process exit status.
Branch on `kind`, not on message text. A listing that stopped at `--limit` says so with `meta.limitReached: true`; raise
`--limit` or pass `--all` for the rest.

Diagnostics go to stderr and never contaminate the document on stdout. `--log-format jsonl`
makes them machine-readable too.

Ask a command what it returns rather than looking a schema up: `bb <command> --describe`
prints an outline of its output, and `--describe --json` a `description` member holding the
JSON Schema of the whole document a run writes (`run.outputSchema`) and of the one
`--dry-run` writes (`dryRun.outputSchema`), derived from the same model the command fills
in, so it cannot disagree with what you get. A command without a schema says why in
`run.reason`. `bb --describe` lists every command with what `--dry-run` does for it.

State-changing commands accept `--dry-run`, which answers with a verdict on the real run
without applying it: under `--json`, a `preview` member with a tier, one effect per change
(`would-apply`, `no-op` or `would-fail`, with reasons), and the `error` the run would fail
with. Use it before a write when you need to show the user what will happen.

Prefer the published command reference over guessing flags or subcommands.

## Links

- [Docs home](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/): Main navigation for operators and agents
- [Installation and Quickstart](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/installation-and-quickstart/): Install, authenticate, and run first commands
- [Command Reference](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/reference/commands/): Exact public command surface and flags
- [JSON Schemas](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/reference/schemas/): Machine contracts for output and configuration files
- [Machine Mode and Diagnostics](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/advanced/machine-mode-diagnostics/): JSON envelope contract and supportability patterns
- [Basic Usage](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/basic-usage/): Common workflows and command patterns
- [Troubleshooting](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/troubleshooting/): The messages bb prints when setup is wrong, and what each means
- [Advanced Topics](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/advanced/): Dry-run, diagnostics, and repository discovery
- [AI and llms.txt overview](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/ai-and-llms/): How this file and the AI tooling fit together
- [MCP setup per client](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/how-to/mcp-clients/): The server entry for Claude Code, Claude Desktop, Cursor and VS Code
- [Architecture Decision Records](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/adr/): Design rationale and system constraints
- [Changelog](https://vriesdemichael.github.io/bitbucket-data-center-cli/latest/changelog/): Release history and release notes
- [bb AI skill (SKILL.md)](https://github.com/vriesdemichael/bitbucket-data-center-cli/blob/main/skills/bb/SKILL.md)

If you hit behaviour that does not match this file, open an issue at
<https://github.com/vriesdemichael/bitbucket-data-center-cli/issues/new>, or ask the user
to file one for you.