Skip to content
Bitbucket CLIBitbucket CLI

Quick Start

TL;DR

Section titled “TL;DR”
Terminal window
npm install -g @pilatos/bitbucket-cli
bb auth login
bb repo clone myworkspace/myrepo
bb pr create -t "My feature"

Prerequisites

Section titled “Prerequisites”
  • Bun runtime 1.0+. Installing via npm or pnpm does not install Bun. Without it, bb exits with Error: This CLI requires the Bun runtime. See Installation.
  • A Bitbucket Cloud account.

Step-by-step setup

Section titled “Step-by-step setup”

  1. Install the CLI

    Terminal window
    npm install -g @pilatos/bitbucket-cli

    Verify the installation:

    Terminal window
    bb --version

  2. Authenticate

    Terminal window
    bb auth login

    This opens your browser to authorize the CLI with your Bitbucket account. No token setup needed.

    For CI/CD or headless environments, pipe an API token in on stdin:

    Terminal window
    echo "$BB_API_TOKEN" | bb auth login -u your-username --with-token

    If BB_API_TOKEN is set in your environment, a bare bb auth login uses API token auth instead of OAuth.

    Verify it worked:

    Terminal window
    bb auth status

    See the Authentication guide for full details.

  3. Clone a repository

    Terminal window
    bb repo clone myworkspace/myrepo
    cd myrepo

  4. Create your first pull request

    Terminal window
    git checkout -b feature/my-feature
    # Make some changes...
    git add .
    git commit -m "Add my feature"
    git push -u origin feature/my-feature
    

    bb pr create -t "Add my feature"

Common commands

Section titled “Common commands”
Command Description
bb pr list List open pull requests
bb pr view 42 View PR #42 details
bb pr activity 42 View PR #42 activity log
bb pr create -t "Title" Create a new PR
bb pr merge 42 Merge PR #42
bb pr checkout 42 Checkout PR #42 locally
bb pr diff 42 View PR #42 diff
bb repo list List repositories
bb browse 42 Open PR #42 in your browser
bb browse src/cli.ts:20 Open a file at a specific line in your browser
bb api /user Call any Bitbucket API endpoint (escape hatch)

Set a default workspace

Section titled “Set a default workspace”

Not sure what your workspace slug is? List the workspaces you have access to:

Terminal window
bb workspace list

If you work primarily in one workspace, set it as default:

Terminal window
bb config set defaultWorkspace myworkspace

Now commands will use this workspace automatically:

Terminal window
bb repo list          # Lists repositories in "myworkspace"
bb pr list -r myrepo  # Lists PRs in "myworkspace/myrepo"

Enable tab completion

Section titled “Enable tab completion”
Terminal window
bb completion install

Restart your shell, then try:

Terminal window
bb <Tab>                         # Shows every top-level command
bb pr <Tab>                      # Shows: activity, approve, checkout, checks, comments, create, decline, diff, edit, list, merge, ready, reviewers, view
bb pr create -<Tab>              # Shows available flags
bb pr merge 42 --strategy <Tab>  # Shows: merge_commit, squash, fast_forward, ...

Scripting with JSON

Section titled “Scripting with JSON”

Every command accepts --json for machine-readable output. You can project to a comma-separated field list and filter results through a built-in jq engine — no external jq binary required:

Terminal window
# Project to specific fields
bb pr list --json id,title,state


# Filter through built-in jq
bb pr list --json --jq '.pullRequests[] | select(.state == "OPEN") | .title'

Update notifications

Section titled “Update notifications”

When a newer version is available on npm, bb writes a one-time notice to stderr after the next command finishes:

──────────────────────────────────────────────────
A new version is available: 1.23.0 (you have 1.22.0)
  Run 'bun install -g @pilatos/bitbucket-cli' to update
  Or disable with 'bb config set skipVersionCheck true'
──────────────────────────────────────────────────

Under --no-unicode or BB_NO_UNICODE, the horizontal rules are drawn with - instead of ─.

The notice never appears with --json, when stderr is not a TTY, or in CI environments. The check itself runs at most once every versionCheckInterval days (default: 1). Disable it permanently with:

Terminal window
bb config set skipVersionCheck true

See the Configuration File reference for related settings.

Next steps

Section titled “Next steps”