Skip to content
Bitbucket CLIBitbucket CLI

Bitbucket CLI

Clone repositories, manage pull requests, and automate workflows from your terminal. If you know GitHub's gh, you'll feel right at home.
Get StartedView on GitHub

Install

Section titled “Install”

Requires Bun 1.0+ runtime.

Terminal window
npm install -g @pilatos/bitbucket-cli
Terminal window
bb auth login                          # authenticate
bb repo clone myworkspace/myrepo       # clone a repository
bb pr create -t "My awesome feature"   # create a PR
bb pr list                             # list open PRs

What can you do?

Section titled “What can you do?”

Repository management

Clone, create, list, view, and delete repositories.

Terminal window
bb repo clone workspace/repo
bb repo create my-new-project
bb repo list -w myworkspace

Pull requests

Full PR lifecycle — create, review, approve, merge.

Terminal window
bb pr create -t "Add feature"
bb pr approve 42
bb pr merge 42 --strategy squash

Code review

View diffs, checkout PR branches, inspect checks.

Terminal window
bb pr diff 42
bb pr checkout 42
bb pr checks 42

CI/CD pipelines

Trigger, inspect, and stop Bitbucket Pipelines.

Terminal window
bb pipeline run --branch main
bb pipeline list --status FAILED
bb pipeline logs 42

Workspaces and projects

Find the workspaces you belong to and the projects inside them.

Terminal window
bb workspace list
bb project list
bb project view PROJ

Issues, snippets, and commits

Track issues, share snippets, read history, and publish build statuses.

Terminal window
bb issue list --state open
bb snippet create -t notes -f a.txt
bb commit list --limit 10
bb status set abc1234 --key BB-DEPLOY --state SUCCESSFUL

See Issue commands and Snippet commands.

Jump to the web UI

Open Bitbucket pages — PRs, files, commits, settings — in your browser.

Terminal window
bb browse 42
bb browse src/cli.ts:20
bb browse --pipelines

Scripting and automation

Every command speaks JSON. --json projects to a field list, --jq filters in-process — no external jq binary, no shell pipe.

Terminal window
bb pr list --json id,title,author.display_name
bb pipeline run --branch main --json --jq '.build_number'

A field list returns a flat array of objects; dotted paths keep their full name as the key. See the Scripting guide.

Raw API access

Reach any Bitbucket 2.0 endpoint not yet wrapped by a typed command.

Terminal window
bb api /user
bb api /repositories/{workspace}/{repo}/pullrequests --paginate
bb api POST /repositories/ws/repo/issues -f title=Bug

PR workflows

Section titled “PR workflows”
Create, edit, and viewOpen a PR, change its title or description, list PRs, inspect one.
Review and mergeApprove, decline, mark drafts ready, and merge with explicit strategy control.
Diff and checkoutReview patch output, fetch PR branches locally, and open browser diffs.
Activity and checksInspect activity history and CI/build status before approving or merging.
Review commentsList, add, view, edit, reply to, resolve, unresolve, and delete general or inline review comments.
ReviewersAdd and remove reviewers. Adding someone already assigned is a no-op, as is removing someone who is not.
All PR commands

Explore

Section titled “Explore”
Scripting guideJSON output, exit codes, shell patterns.
CI/CD integrationGitHub Actions, GitLab CI, Jenkins, and more.
RecipesAuto-merge on green CI, bulk reviewer assignment, fork sync, reporting, retry wrappers.
AI agent integrationWire the CLI into coding agents and tool-calling loops.
TroubleshootingCommon issues and solutions.

Community

Section titled “Community”

This is an unofficial, community-maintained CLI. Not affiliated with Atlassian.