Skip to content
Bitbucket CLI Bitbucket CLI

Quick Start

Get productive with the Bitbucket CLI in under a minute.

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”

Before you begin, you’ll need:

  • Bun runtime 1.0+ installed (required to run the CLI)
  • 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, use an API token instead:

    Terminal window
    bb auth login -u your-username -p your-api-token

    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 PR

    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”

Here are the commands you’ll use most often:

CommandDescription
bb pr listList open pull requests
bb pr view 42View PR #42 details
bb pr activity 42View PR #42 activity log
bb pr create -t "Title"Create a new PR
bb pr merge 42Merge PR #42
bb pr checkout 42Checkout PR #42 locally
bb pr diff 42View PR #42 diff
bb repo listList repositories
bb browse 42Open PR #42 in your browser
bb browse src/cli.ts:20Open a file at a specific line in your browser

Set a Default Workspace

Section titled “Set a Default Workspace”

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 repos in "myworkspace"
bb pr list -r myrepo  # Lists PRs in "myworkspace/myrepo"

Enable Tab Completion

Section titled “Enable Tab Completion”

Get intelligent tab completion for commands and options:

Terminal window
bb completion install

Restart your shell, then try:

Terminal window
bb pr <Tab>      # Shows: activity, approve, checkout, create, decline, diff, list, merge, ready, view
bb pr create -<Tab>  # Shows available flags
bb <Tab>         # Shows: auth, repo, pr, snippet, browse, config, completion

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 prints a one-time nudge after the next command finishes:

⚠ A new version is available: 1.14.0 (you have 1.13.0)
  Run 'npm install -g @pilatos/bitbucket-cli' to update
  Or disable with 'bb config set skipVersionCheck true'

The check runs at most once per versionCheckInterval (default: 24 hours) and is skipped automatically in CI environments. 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”

You’re all set! Here’s where to go next: