bitbucket-cli

Low-maintenance Bitbucket Cloud tooling built from the live OpenAPI spec: a CLI for software engineers, an MCP server for AI agents, and a Terraform provider for DevSecOps teams.

[!IMPORTANT] https://github.com/FabianSchurig/bitbucket-cli is the canonical repository. If you found this project through the terraform-provider-bitbucket mirror, watch, star, file issues, and contribute in bitbucket-cli.

Start here

Quick links

• Canonical GitHub repository
• Terraform Registry: FabianSchurig/bitbucket
• Mirror repository: terraform-provider-bitbucket
• GitHub Releases
• SonarQube Cloud
• Contributing guide

Install

Homebrew (macOS & Linux)

To install the CLI tool via our custom tap, tap the repository and explicitly trust the formula to reduce supply chain risks:

brew tap FabianSchurig/tap
brew trust --formula FabianSchurig/tap/bitbucket-cli
brew install bitbucket-cli

Or to install the MCP server:

brew tap FabianSchurig/tap
brew trust --formula FabianSchurig/tap/bitbucket-mcp
brew install bitbucket-mcp

(Note: If you previously tapped the old cask, you can safely untap via brew untap fabianschurig/tap before running the command).

APT (Debian / Ubuntu)

Download the .deb package from the latest release and install it. Supported architectures: amd64, arm64.

TAG_URL=$(curl -fsSIL -o /dev/null -w '%{url_effective}' https://github.com/FabianSchurig/bitbucket-cli/releases/latest)
VERSION=${TAG_URL##*/}
VERSION=${VERSION%%\?*}
VERSION=${VERSION%%\#*}
VERSION=${VERSION#v}
ARCH=$(dpkg --print-architecture)
curl -LO "https://github.com/FabianSchurig/bitbucket-cli/releases/download/v${VERSION}/bb-cli_${VERSION}_${ARCH}.deb"
sudo dpkg -i "bb-cli_${VERSION}_${ARCH}.deb"

Replace bb-cli with bb-mcp to install the MCP server instead.

RPM (Fedora / RHEL / CentOS)

Download the .rpm package from the latest release and install it. Supported architectures: amd64, arm64.

TAG_URL=$(curl -fsSIL -o /dev/null -w '%{url_effective}' https://github.com/FabianSchurig/bitbucket-cli/releases/latest)
VERSION=${TAG_URL##*/}
VERSION=${VERSION%%\?*}
VERSION=${VERSION%%\#*}
VERSION=${VERSION#v}
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -LO "https://github.com/FabianSchurig/bitbucket-cli/releases/download/v${VERSION}/bb-cli_${VERSION}_${ARCH}.rpm"
sudo rpm -i "bb-cli_${VERSION}_${ARCH}.rpm"

Replace bb-cli with bb-mcp to install the MCP server instead.

Scoop (Windows)

scoop bucket add bitbucket https://github.com/FabianSchurig/scoop-bucket
scoop install bb-cli
scoop install bb-mcp

Winget (Windows)

winget install FabianSchurig.bb-cli
winget install FabianSchurig.bb-mcp

Install script

curl -fsSL https://raw.githubusercontent.com/FabianSchurig/bitbucket-cli/main/install.sh | sh

See install.sh options for version selection, binary choice (bb-cli, bb-mcp, or all), and custom install directories.

Other methods

For full installation details see the CLI usage guide and the MCP usage guide.

What this project is

This repository keeps Bitbucket Cloud tooling maintainable by generating most of the surface area from the live Bitbucket OpenAPI spec.

• One API description, three user-facing tools: CLI, MCP, and Terraform all come from the same schema pipeline.
• Thin hand-written runtime: auth, dispatch, output, and Terraform runtime stay generic instead of growing per-endpoint glue.
• Fast spec adoption: new Bitbucket endpoints flow in through generation instead of large manual rewrites.
• Maintenance-first design: the main development effort goes into the shared generators and runtime, not duplicated endpoint code.
• Internal/undocumented endpoints supported the same way: schemas under schema/ can be hand-authored for endpoints that are not in Bitbucket's public OpenAPI spec (for example the project-level branch-restrictions endpoint exposed only via https://bitbucket.org/!api/internal/...). The generators and runtime treat them identically — schema paths may use absolute URLs and the dispatcher passes them through unchanged.

Architecture

flowchart LR
    A[Live Bitbucket OpenAPI spec] --> B[enrich_spec.py]
    B --> C[partition_spec.py]
    C --> D[schema/*-schema.yaml]
    D --> E[oapi-codegen models]
    D --> F[CLI generator]
    D --> G[MCP generator]
    D --> H[Terraform generator]
    E --> I[Shared generated types]
    F --> J[bb-cli]
    G --> K[bb-mcp]
    H --> L[terraform-provider-bitbucket]
    I --> J
    I --> K
    I --> L
    M[Hand-written runtime\nauth, dispatch, output, MCP handler, TF runtime] --> J
    M --> K
    M --> L

In practice:

• CLI exposes Bitbucket operations as terminal commands.
• MCP exposes the same operations as tool calls for AI agents.
• Terraform maps operation groups into generic resources and data sources.
• Hand-written code stays small on purpose; generated code handles endpoint coverage.

CI pipelines

flowchart TD
    A[push / pull_request] --> B[ci.yml]
    A --> C[terraform-tests.yml]
    D[schedule / manual] --> E[schema-sync.yml]
    E --> F[Fetch live spec]
    F --> G[Regenerate code and docs]
    G --> H[Build and test]
    H --> I[Tag new version]
    I --> J[release.yml]
    J --> K[docker.yml]
    I --> L[terraform-release.yml]
    K --> M[Publish to MCP Registry]

• ci.yml: builds, lints, vets, runs Go tests, and sends analysis to SonarQube Cloud.
• terraform-tests.yml: runs mock-based Terraform acceptance and terraform test suites, plus real API tests when credentials exist. See docs/e2e-coverage.md for the current list of endpoints exercised by the real-API tests.
• schema-sync.yml: daily/manual sync that fetches the live Bitbucket spec, regenerates generated artifacts, rebuilds docs, tests everything, and tags a release when the schema changed.
• release.yml: publishes tagged binary releases via GoReleaser.
• docker.yml: builds multi-arch container images for bb-cli and bb-mcp, pushes them to GHCR, publishes their SBOM and CVE reports (see Supply chain: SBOM and CVE reports), and publishes the bb-mcp server to the MCP Registry.
• terraform-release.yml: mirrors the tagged source into terraform-provider-bitbucket and publishes the Terraform provider release.

Schema sync safety

The live OpenAPI document is treated as an input, not as an authority to delete a working API group because of a transient omission. Three mechanisms keep the daily sync from breaking published surface or itself: