Skip to content

Basic Usage

What you can manage

bb supports operational workflows across:

  • Authentication and server context (auth)
  • Repository settings and collaboration (repo, reviewer, branch, tag, commit, ref)
  • Pull requests and quality controls (pr, build, insights)
  • Project-level administration (project, admin)
  • Cross-project discovery (search)
  • gh-style repository ergonomics for Bitbucket (repo clone, browse)

Project-level settings cascade to every repository in the project, so bb project permissions, bb project webhook, bb project default-task and bb project branch-restriction are how a policy is applied across many repositories at once.

Use All Commands for complete command and argument coverage.

Command discovery pattern

bb --help
bb repo --help
bb repo settings --help
bb repo settings security --help

The command reference is generated from the command tree, so its usage and flags match the binary.

Shorter spellings and aliases

Some operations are reachable under a second, shorter name because that is the name people (and coding agents) reach for first. Both spellings run the same command and produce identical output; each one's --help names the other so you can discover either form.

bb pr diff 42
bb repo create --project PROJ --name my-repo
bb repo fork --name my-fork --repo PROJ/my-repo
bb repo delete --repo PROJ/my-fork
bb repo permissions list --repo PROJ/my-repo
bb repo permissions grant alice REPO_WRITE --repo PROJ/my-repo
bb repo permissions grant --group developers REPO_READ --repo PROJ/my-repo
bb project permissions grant TEST alice PROJECT_WRITE
Shorter / Elevated Deep Path / Alias Notes
bb pr diff bb diff pr bb diff pr is canonical in reference
bb repo create bb repo admin create bb repo create is canonical
bb repo fork bb repo admin fork bb repo fork is canonical
bb repo delete bb repo admin delete bb repo delete is canonical
bb repo permissions list / grant / revoke bb repo settings security permissions users … --group replaces groups segment
bb project permissions list / grant / revoke bb project permissions users … --group replaces groups segment

--group is what replaces the users / groups path segment on permission commands. Omitting it means a user, so it is worth being deliberate about on a grant.

Pull request target resolution

Commands operating on a pull request (bb pr get, bb pr checkout, bb pr diff, bb pr review, bb pr comment, bb pr merge, etc.) resolve the target flexibly:

  • Numeric ID: 42
  • Hash prefix: #42
  • Source branch name: feature/login, refs/heads/feature/login
  • Full Bitbucket URL: https://bitbucket.example.com/projects/PRJ/repos/demo/pull-requests/42 (also supports personal repos ~username and /diff, /commits, /overview subpaths)

When you pass a full PR URL, bb automatically extracts the project, repository slug, and pull request ID, so you do not even need to supply --repo or stand inside a local clone:

# Target via full browser PR URL (no local git clone needed)
bb pr get https://bitbucket.example.com/projects/PRJ/repos/demo/pull-requests/42

# Diff via PR URL
bb pr diff https://bitbucket.example.com/projects/PRJ/repos/demo/pull-requests/42

# Check out via source branch name or hash
bb pr checkout feature/payment-gateway
bb pr checkout '#42'

bb pr status

Not a shorter spelling but a view of its own: the pull requests on your current branch, the ones you opened, and the ones waiting on your review, across every repository.

bb pr status

The review section shows only what you have not responded to yet — the same set Bitbucket's own dashboard shows. Pull requests you already approved or sent back as needing work are waiting on their author, not on you.

The current-branch section needs a git checkout with a Bitbucket remote. Outside one, it reports why in a note and the other two sections still answer.

bb pr checkout

Checks out a pull request's source branch in the repository you are standing in, so you can run it, review it, and push fixes back.

bb pr checkout 42
bb pr checkout '#42'
bb pr checkout feature/login
bb pr checkout https://bitbucket.example.com/projects/PRJ/repos/demo/pull-requests/42
bb pr checkout 42 --branch review-42
bb pr checkout 42 --detach

Pull requests from a fork work too, and are the reason to use this rather than a manual git fetch. bb fetches from the fork, adding a remote for it if you do not have one, and sets the branch upstream so a later plain git push goes back to the fork branch the pull request is built from. The local branch is prefixed with the fork owner (jdoe/fix-login) so it cannot collide with a branch of the same name of your own.

Running it again on the same pull request fast-forwards the branch you already have. If the branch has diverged from the pull request, that fails rather than merging or discarding anything.

A working tree with uncommitted changes to tracked files is refused; pass --force to discard them. Untracked files are ignored, so build output does not get in the way.

The fetch uses the credentials bb is already authenticated with, so this works immediately after bb repo clone with no git credential setup. The credential is passed to that one git invocation and never written into the repository.

Pushing afterwards is plain git, which does not go through bb — run bb auth setup-git once to let it authenticate. See Git Authentication.

bb pr create

Inside a checkout, bb pr create works out what it is not told:

Flag Taken from
--from-ref The branch that is checked out
--to-ref The repository's default branch
--title The subject of the branch's commit, when it holds exactly one 
git push -u origin feature/login
bb pr create

At a terminal each is offered for you to accept or change. With nobody to ask, in CI or under --no-input or --json, they are used as they are and named on stderr, and --title is still required for a branch that holds several commits. The checked-out branch is only taken unasked when the repository itself came from the checkout: with --repo naming one, pass --from-ref.

It prints the pull request's link, and --json carries it as url.

Reviewers

bb pr create fills in reviewers exactly as the web interface does: the default reviewer conditions for the branch pair, plus the code owners matching the diff. Bitbucket resolves the code owners, not bb, so the .bitbucket/CODEOWNERS syntax and its meaning are the server's and the answer matches the web interface (ADR-080). If a lookup fails, bb says so and still creates the pull request.

# Default reviewers and code owners are applied automatically
bb pr create --from-ref feature/login --to-ref main --title "Add login"

# Opt out of either or both
bb pr create --from-ref feature/login --to-ref main --title "Add login" --no-default-reviewers --no-codeowners

# Name reviewers and reviewer groups explicitly (repeatable or comma-separated)
bb pr create --from-ref feature/login --to-ref main --title "Add login" --reviewers alice,bob --reviewer-group backend-team

# @group works anywhere a reviewer is accepted
bb pr create --from-ref feature/login --to-ref main --title "Add login" --reviewers alice,@backend-team

For a pull request that already exists the same automation is available, opt-in:

bb pr review reviewer add 42 --user alice --user bob --reviewer-group core-team
bb pr review reviewer add 42 --default-reviewers --codeowners

Repository context behavior

  • --repo PROJECT/slug has highest precedence. --repo also accepts full Bitbucket repository URLs (https://bitbucket.example.com/projects/PRJ/repos/demo) and personal user repositories (~username/slug).
  • If --repo is omitted, bb can infer repository context from local git remotes that match authenticated hosts.
  • When several remotes match, origin wins — a fork or mirror alongside it does not make the context ambiguous.
  • An upstream remote is the exception: it conventionally outranks origin, so having both is a genuine ambiguity and bb asks for explicit selection.

See Advanced: Repository Discovery and Server Switching for remote URL formats, precedence, ambiguity handling, and multi-server workflows.

Prompts and the non-interactive contract

bb prompts only where a person can answer (ADR-073). With no terminal, or under --json, no command blocks on standard input: it fails fast and names the flag or value it needed, which is what keeps scripts, CI/CD pipelines and AI agent tool calls predictable. A command that deletes, removes, revokes or clears something asks for confirmation at a terminal, and requires --yes when there is nobody to ask.

Dry-run behavior and scope

  • A command that changes something on the server is checked against Bitbucket, or predicted, and not run.
  • A command that changes this machine (stored credentials, host aliases, git configuration, the skill file, shell completion, a clone or a local branch) is previewed and not run.
  • A command that changes nothing runs as usual.
  • bb ai mcp serve does not take the flag: it starts a live server, and a session cannot be previewed.
  • The answer is a verdict with the reasons for it. A dry run that finds the run would fail exits with the code the real run would; under --json or --yaml it exits 0, with the verdict in the document.

See Advanced: Dry-Run Planning for safety and contract details.

Machine output (--json, --yaml)

--json prints one document, and --yaml the same document as YAML. The command's result is under data, and meta says which command and which bb produced it:

{
  "data": {},
  "meta": {
    "command": "auth status",
    "bbVersion": "v6.1.0"
  }
}

A field added to data is additive. Removing or renaming one, changing its type, or changing whether it can be null is a breaking change and cuts a major release (ADR-064). bb <command> --describe lists the fields a command returns, and Machine Mode and Diagnostics covers the failure document, dry runs, exit codes and diagnostics.

Configuration and authentication

A flag wins over an environment variable, a variable over the configuration files, and a file over the built-in default; a setting an administrator mandates outranks all of them. Configuration gives the order for each setting and what each file holds. bb authenticates with a token, or with a username and password.

That configuration governs how bb authenticates to the Bitbucket API. Plain git authenticates separately: it does not read bb's configuration, so git push and git pull inside a clone need bb auth setup-git once per host. Credentials are never written into a repository — see Git Authentication.

Quick examples

bb --json auth status
bb repo clone PROJ/my-repo
bb repo create --project PROJ --name my-service
bb repo fork --repo PROJ/my-service --name my-service-fork
bb pr get https://bitbucket.example.com/projects/PROJ/repos/my-service/pull-requests/42
bb pr checkout '#42'
bb pr diff feature/payments
bb browse --repo PROJ/my-repo src/main.go
bb search repos demo --limit 20
bb tag list --repo PROJ/my-repo --limit 50
bb --dry-run project create DEMO --name "Demo Project"

When a command does not do what you expected

bb doctor reports every problem in every configuration file at once, and where each effective setting comes from. It needs no host and no network:

bb doctor