Skip to content
Bitbucket CLI

Quick Start

Get productive with the Bitbucket CLI in under a minute.

TL;DR

Terminal window
npm install -g @pilatos/bitbucket-cli
bb auth login -u your-username -p your-api-token
bb repo clone myworkspace/myrepo
bb pr create -t "My feature"

Prerequisites

Before you begin, you’ll need:

  • Node.js 20+ or Bun installed
  • A Bitbucket Cloud account
  • An API token (we’ll create one below)

Step-by-Step Setup

  1. Install the CLI

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

    Verify the installation:

    Terminal window
    bb --version

  2. Create an API Token

    1. Go to Bitbucket API Tokens
    2. Click Create API token
    3. Name it (e.g., “bb CLI”)
    4. Select scopes:
      • Account: Read
      • Repositories: Read, Write
      • Pull requests: Read, Write
    5. Click Create and copy the token

  3. Authenticate

    Terminal window
    bb auth login

    Enter your Bitbucket username and the API token when prompted.

    Verify it worked:

    Terminal window
    bb auth status

  4. Clone a Repository

    Terminal window
    bb repo clone myworkspace/myrepo
    cd myrepo

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

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

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

Terminal window
bb config set workspace 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

Get intelligent tab completion for commands and options:

Terminal window
bb completion install

Restart your shell, then try:

Terminal window
bb pr <Tab>      # Shows: approve, checkout, create, decline, diff, list, merge, view
bb pr create -<Tab>  # Shows available flags

Next Steps

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