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

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

Next Steps

Section titled “Next Steps”

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