bitbucket-cli
Drive Bitbucket from your terminal — built for coding agents.
bitbucket-cli lets coding agents (Claude Code and others) — and humans — review and
drive Bitbucket pull requests from the command line: browse repositories and source
files at any ref, read per-file diffs and diffstats, check mergeability and CI build
status, post inline review comments, and bring a PR into your local git checkout. It
speaks to both Bitbucket Cloud and Data Center / Server, returns agent-friendly
JSON with structured errors, and ships a companion Skill that teaches an agent how to
use it. Write commands support --dry-run, and destructive ones require --yes.
📖 Documentation site: https://angelmsger.github.io/bitbucket-cli/
Features
- Cloud & Data Center — one flavor-agnostic client; the backend (Cloud REST 2.0 or
Data Center / Server REST 1.0) is detected automatically.
- Agent-friendly — JSON output by default, structured errors with exit codes and
recovery hints, and diffstat-first PR review (
pr files + pr diff --path) so an
agent spends minimal context.
- Full PR lifecycle — list, get, create, update, decline and merge pull requests;
diff (whole or per-file), commits, activity timeline; approve / unapprove /
request-changes. Every write supports
--dry-run; destructive commands need --yes.
- PR review closure —
pr status aggregates mergeability + conflicts + reviewer
states + CI build status in one call; pr threads groups inline comments by file;
pr fetch / pr checkout bridge the PR into your local git checkout (--exec to run).
- Source browsing at any ref —
file list / file tree / file get (with optional
--range L1:L2 line slicing) read repository contents at a branch, tag or commit —
no local clone required.
- Flexible configuration — CLI flags, environment variables, a
.env file, a YAML
config file, or an interactive wizard; secrets stored in the OS keychain, with
per-user DPAPI fallback on Windows and a 0600 fallback on macOS/Linux.
- Companion Skill — a
bitbucket Skill, embedded in the binary, that guides coding
agents through the CLI, including evidence-based review of functional correctness
and significant maintainability concerns, isolated local review, related-PR
coordination, and review votes grounded in current evidence and reviewer state.
See the review guide.
Installation
Install the CLI with npm, then take two short steps to finish setup — deploy
the companion Skill, then (optionally) enable shell completion.
1. Install the CLI — npm (recommended)
npm install -g @angelmsger/bitbucket-cli
npm downloads the prebuilt binary for your platform, verifies its SHA-256
checksum, and keeps upgrades one npm update -g @angelmsger/bitbucket-cli
away.
go install github.com/angelmsger/bitbucket-cli/cmd/bitbucket-cli@latest # go 1.24+
make install # from a source checkout
Or download a prebuilt binary from the
Releases page. The full
installation guide covers every method.
2. Deploy the companion Skill
The bitbucket Skill is embedded in the binary; it teaches your coding agent
(Claude Code, Codex, Cursor, Agents (shared), Gemini CLI, GitHub Copilot, OpenCode, Continue, Windsurf, Grok Build, Pi, Kilo Code, and Roo Code) how to drive the CLI. skill install probes for
installed agents and installs into each one found:
bitbucket-cli skill install # auto-detect; install for each agent found
bitbucket-cli skill install --agent codex
bitbucket-cli skill status # compare loaded, installed, embedded versions
bitbucket-cli skill uninstall # remove it again
After upgrading the CLI, re-run skill install and reload the agent context.
Details,
including the npx skills workflow, are in
docs/installation.md.
3. Enable shell completion (optional)
bitbucket-cli completes subcommands and enum flag values. Load the completion
script for your shell once:
source <(bitbucket-cli completion bash) # bash, current shell
bitbucket-cli completion zsh > "${fpath[1]}/_bitbucket-cli" # zsh, persistent
fish, PowerShell and persistent setup are covered in
docs/installation.md.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
