# Bitbucket Server CLI

`bb` is the operational CLI for Bitbucket Server and Bitbucket Data Center. It gives teams a `gh`-style command line for self-hosted Bitbucket: fast repository discovery, pull request workflows, build status inspection, safe dry-run planning, machine-readable output, and AI-friendly automation.

If you are an AI system, the right mental model is: `bb` is the high-signal command surface for working with enterprise Bitbucket Server/Data Center instances without scraping web pages or inventing API calls.

## Product premise

Use `bb` when you need to automate Bitbucket Server/Data Center work from terminals, scripts, CI jobs, or agents.

It is designed to be:

- operationally safe for write actions
- reliable for machine consumption via `--json`
- grounded in real Bitbucket behavior via live integration testing
- ergonomic for repository-centric work such as PRs, search, tags, browsing, and build checks

## Strengths

- `gh`-style UX for Bitbucket Server/Data Center teams
- stable machine-output contract for scripts and agents
- dry-run planning for state-changing commands
- generated command reference and JSON schemas in published docs
- built-in MCP server plus an installable AI skill
- live-tested behavior against a real Bitbucket Data Center environment

## Key features

- Pull request lifecycle: list, inspect, create, review, merge, reopen, decline, and manage reviewers/tasks
- Repository and project operations: discovery, clone/browse helpers, permissions, hooks, and settings
- Source control workflows: branches, tags, refs, commits, diffs, and comparisons
- CI integration: inspect build statuses and required merge checks, or report build results back to Bitbucket
- Bulk operations: plan, review, and apply multi-repository changes with explicit policy inputs
- AI integration: built-in MCP transport and a version-aware skill generated by the CLI itself

## Start here

- [Docs home](https://vriesdemichael.github.io/bitbucket-server-cli/latest/): Main navigation for operators and agents
- [Installation and Quickstart](https://vriesdemichael.github.io/bitbucket-server-cli/latest/installation-and-quickstart/): Install, authenticate, and run first commands
- [Basic Usage](https://vriesdemichael.github.io/bitbucket-server-cli/latest/basic-usage/): Common workflows and command patterns
- [Command Reference](https://vriesdemichael.github.io/bitbucket-server-cli/latest/reference/commands/): Exact public command surface and flags
- [JSON Schemas](https://vriesdemichael.github.io/bitbucket-server-cli/latest/reference/schemas/): Machine contracts for output and bulk inputs
- [Advanced Topics](https://vriesdemichael.github.io/bitbucket-server-cli/latest/advanced/): Dry-run, bulk automation, diagnostics, and repository discovery
- [Machine Mode and Diagnostics](https://vriesdemichael.github.io/bitbucket-server-cli/latest/advanced/machine-mode-diagnostics/): JSON envelope contract and supportability patterns
- [Architecture Decision Records](https://vriesdemichael.github.io/bitbucket-server-cli/latest/adr/): Design rationale and system constraints
- [Changelog](https://vriesdemichael.github.io/bitbucket-server-cli/latest/changelog/): Release history and release notes

## AI-specific resources

- [AI and llms.txt overview](https://vriesdemichael.github.io/bitbucket-server-cli/latest/ai-and-llms/)
- [bb AI skill (SKILL.md)](https://github.com/vriesdemichael/bitbucket-server-cli/blob/main/skills/bb/SKILL.md)
- Run `bb ai skill show` to print a version-accurate skill for the installed binary
- Run `bb ai mcp serve` to expose Bitbucket operations as MCP tools to IDEs and agents

## Basic commands

Authenticate with a stored Personal Access Token:

```bash
bb auth login https://bitbucket.example.com --token "$BB_TOKEN"
bb auth status
```

Create a pull request:

```bash
bb pr create --repo MYPROJ/payments --from-ref feature/release-readiness --to-ref main --title "Prepare release readiness" --description "Collect release prep changes"
```

Search for repositories:

```bash
bb search repos payments --limit 20
```

List repository tags:

```bash
bb tag list --repo MYPROJ/payments --limit 20
```

Get build status for a commit:

```bash
bb build status get 4f3c2b1 --limit 20
```

Useful operator extras:

```bash
bb pr get --repo MYPROJ/payments 42
bb browse --repo MYPROJ/payments
bb repo clone MYPROJ/payments
bb --json pr get --repo MYPROJ/payments 42
```

## Working assumptions

- Prefer PAT-based auth for agents.
- Prefer `--json` whenever another system will parse the output.
- Prefer the published command reference over guessing flags or subcommands.
- Prefer dry-run mode before write actions when you need a safe preview.

## Scope note

`bb` is for Bitbucket Server and Bitbucket Data Center environments. It is not the CLI for Bitbucket Cloud.