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
cd myrepo
# Push your feature branch before creating a pull request.
bb pr create -t "My feature"

Prerequisites

Section titled “Prerequisites”
  • Bun runtime 1.1.30+ for the npm package. Installing via npm or pnpm does not install Bun. Without it, bb fails to start with an error that bun was not found, such as env: bun: No such file or directory. The standalone binary needs no runtime.
  • 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

    In an interactive terminal, choose OAuth to authorize in your browser, or API token to enter your email and token. Without prompts, a bare login starts OAuth unless API-token flags or BB_API_TOKEN select token auth.

    For CI/CD or headless environments, load BB_API_TOKEN from your secret store and pipe it in on stdin. -u takes your Atlassian account email:

    Terminal window
    printf '%s' "$BB_API_TOKEN" | bb auth login -u [email protected] --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

On PowerShell (or to load the script yourself in any shell), print it with bb completion <bash|zsh|fish|powershell>; see Completion Commands.

Terminal window
Add-Content $PROFILE 'bb completion powershell | Out-String | Invoke-Expression'

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'
──────────────────────────────────────────────────

The update line follows where bb is installed: pnpm add -g for a pnpm global install, bun install -g for a Bun global install, a download link for the standalone binary, and npm install -g for any other node_modules install. Outside node_modules, such as a source checkout, it suggests bun install -g.

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”