---
search:
  boost: 2.0
---

# Basic Usage

## What you can manage

`bb` supports operational workflows across:

- Authentication and server context (`auth`)
- Repository settings and collaboration (`repo`, `reviewer`, `hook`, `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](reference/commands/index.md) for complete command and argument coverage.

## Command discovery pattern

```bash
bb --help
bb repo --help
bb repo settings --help
bb repo settings security --help
```

The command reference page is generated from Cobra help output, so usage/flags match CLI behavior.

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

```bash
bb pr diff 42
bb repo create --project TEST --name my-repo
bb repo fork --name my-fork --repo TEST/my-repo
bb repo delete --repo TEST/my-fork
bb repo permissions list --repo TEST/my-repo
bb repo permissions grant alice REPO_WRITE --repo TEST/my-repo
bb repo permissions grant --group developers REPO_READ --repo TEST/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.acme.corp/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:

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

# Diff via PR URL
bb pr diff https://bitbucket.acme.corp/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.

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

```bash
bb pr checkout 42
bb pr checkout '#42'
bb pr checkout feature/login
bb pr checkout https://bitbucket.acme.corp/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](advanced/git-authentication.md).

## 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](adr/080-bitbucket-resolves-codeowners-not-bb.md)). If a lookup fails, `bb`
says so and still creates the pull request.

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

```bash
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.acme.corp/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](advanced/repository-discovery-and-server-switching.md)
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](adr/073-interactive-when-a-person-is-there-explicit-when-not.md)).
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

- `--dry-run` applies to server-mutating Bitbucket commands.
- `--dry-run` does not apply to local auth/config mutators.
- Dry-run output includes explicit planning metadata such as planning mode and capability signaling.
- For bulk workflows, `bulk plan` is the preview mechanism and `bulk apply` executes reviewed plans.

See [Advanced: Dry-Run Planning](advanced/dry-run-planning.md) for safety and contract details.

## Machine mode (`--json`)

- Machine responses are wrapped in a standard envelope:

<!-- docs-lint: envelope-shape -->
```json
{
  "data": {},
  "meta": {
    "bbVersion": "[[ bb_version_tag ]]"
  }
}
```

- `data` contains the command-specific payload shape.
- Adding a field 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 new major release, because the binary
  version is the contract version ([ADR-064](adr/064-machine-output-carries-no-contract-version.md)).
  `meta.bbVersion` reports which binary produced the document.

Example machine output (`bb --json auth status`):

<!-- docs-lint: output-of bb auth status -->
```json
{
  "data": {
    "ok": true,
    "bitbucketUrl": "https://bitbucket.acme.corp",
    "bitbucketVersionTarget": "",
    "authMode": "token",
    "authSource": "stored",
    "credentialStorage": "keyring",
    "checks": [
      { "name": "authentication", "ok": true, "advisory": false },
      { "name": "git credential helper", "ok": true, "advisory": true }
    ]
  },
  "meta": {
    "bbVersion": "[[ bb_version_tag ]]"
  }
}
```

## Config and auth precedence

Runtime precedence order:

1. CLI flags
2. Environment variables / `.env`
3. Git remote inference (repo + host context)
4. Stored config (`%AppData%\bb\config.yaml`, `~/Library/Application Support/bb/config.yaml` or `~/.config/bb/config.yaml`) + keyring/fallback secrets
5. Built-in defaults

Supported day-to-day authentication modes are token and basic auth.

That precedence 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](advanced/git-authentication.md).

## Quick examples

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

Example human output (`bb auth status`):

```text
Target Bitbucket: https://bitbucket.acme.corp (auth=token, source=stored)
```

`authSource` says where the credential came from: `stored` from a configuration
file or the keyring, `env` from `BITBUCKET_TOKEN` or the basic-auth variables,
and `env/default` when neither supplied one.

`bitbucketVersionTarget` is empty unless an operator pinned a version by setting
`BITBUCKET_VERSION_TARGET`, and the human rendering leaves the version out
entirely when it is. It records a version for your own environment; `bb` does
not pin one, and nothing branches on it.

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

```bash
bb doctor
```

- [Troubleshooting](troubleshooting.md): the messages people hit, and what each one means
- [Coming from `gh`](gh-parity.md): the `bb` command behind each `gh` one
- [Machine Mode and Diagnostics](advanced/machine-mode-diagnostics.md): error kinds, exit codes and traces