bitbucket-cli

# bitbucket-cli

[![CI](https://github.com/FabianSchurig/bitbucket-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/FabianSchurig/bitbucket-cli/actions/workflows/ci.yml)
[![GitHub Release](https://img.shields.io/github/v/release/FabianSchurig/bitbucket-cli)](https://github.com/FabianSchurig/bitbucket-cli/releases)
[![Terraform Registry](https://img.shields.io/badge/terraform-registry-623CE4)](https://registry.terraform.io/providers/FabianSchurig/bitbucket/latest)
[![Sonar Quality Gate](https://sonarcloud.io/api/project_badges/quality_gate?project=FabianSchurig_bitbucket-cli)](https://sonarcloud.io/summary/new_code?id=FabianSchurig_bitbucket-cli)
[![Sonar Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=FabianSchurig_bitbucket-cli&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=FabianSchurig_bitbucket-cli)
[![Sonar Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=FabianSchurig_bitbucket-cli&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=FabianSchurig_bitbucket-cli)
[![Sonar Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=FabianSchurig_bitbucket-cli&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=FabianSchurig_bitbucket-cli)
[![Sonar Security Rating](https://sonarcloud.io/api/project_badges/measure?project=FabianSchurig_bitbucket-cli&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=FabianSchurig_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

| Audience | Best fit | Start here |
| --- | --- | --- |
| DevSecOps engineers | Terraform provider | [Terraform Registry](https://registry.terraform.io/providers/FabianSchurig/bitbucket/latest), [generated provider docs](./docs/index.md), [example: `bitbucket_tags`](https://registry.terraform.io/providers/FabianSchurig/bitbucket/latest/docs/resources/tags) |
| Software engineers / computer scientists | `bb-cli` | [CLI usage guide](./docs/cli.md) |
| AI agents / agent platform users | `bb-mcp` | [MCP usage guide](./docs/mcp.md) |

## Quick links

- [Canonical GitHub repository](https://github.com/FabianSchurig/bitbucket-cli)
- [Terraform Registry: `FabianSchurig/bitbucket`](https://registry.terraform.io/providers/FabianSchurig/bitbucket/latest)
- [Mirror repository: `terraform-provider-bitbucket`](https://github.com/FabianSchurig/terraform-provider-bitbucket)
- [GitHub Releases](https://github.com/FabianSchurig/bitbucket-cli/releases)
- [SonarQube Cloud](https://sonarcloud.io/project/overview?id=FabianSchurig_bitbucket-cli&organization=fabianschurig)
- [Contributing guide](./CONTRIBUTING.md)

## 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:

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

Or to install the MCP server:

```bash
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](https://github.com/FabianSchurig/bitbucket-cli/releases/latest) and install it. Supported architectures: `amd64`, `arm64`.

```bash
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](https://github.com/FabianSchurig/bitbucket-cli/releases/latest) and install it. Supported architectures: `amd64`, `arm64`.

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

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

### Winget (Windows)

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

### Install script

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

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

### Other methods

| Method | Command |
| --- | --- |
| Go install | `go install github.com/FabianSchurig/bitbucket-cli/cmd/bb-cli@latest` |
| Docker | `docker pull ghcr.io/fabianschurig/bitbucket-cli:latest` |
| Download binaries | [GitHub Releases](https://github.com/FabianSchurig/bitbucket-cli/releases) |

For full installation details see the [CLI usage guide](./docs/cli.md) and the [MCP usage guide](./docs/mcp.md).

## 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

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

```mermaid
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](./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](#supply-chain-sbom-and-cve-reports)), and publishes the `bb-mcp` server to the [MCP Registry](https://registry.modelcontextprotocol.io).
- **`terraform-release.yml`**: mirrors the tagged source into `terraform-provider-bitbucket` and publishes the Terraform provider release.

## Supply chain: SBOM and CVE reports

Every released container image ships with a Software Bill of Materials and a vulnerability report in standard formats. Both are produced from the exact image digest that was pushed to GHCR.

| Artifact | Format | Where to get it |
| --- | --- | --- |
| Image SBOM | SPDX 2.3 JSON | `sbom-bitbucket-cli.spdx.json` / `sbom-bitbucket-mcp.spdx.json` on the matching [GitHub Release](https://github.com/FabianSchurig/bitbucket-cli/releases), or as a signed attestation on the image itself |
| Image CVE report | Grype JSON + plain-text table | `cves-bi