bb - Bitbucket CLI

A lightweight Bitbucket CLI that mirrors glab's UX. Manage pull requests, pipelines, and more from your terminal.

Install

npm install -g @ganeshgaxy/bb-cli

Requires Node.js >= 18.

Quick Start

# Authenticate (supports App Passwords, Atlassian API Tokens, OAuth tokens)
bb auth login

# List open pull requests
bb pr list -R workspace/repo

# Create a pull request
bb pr create --title "Fix bug" --description "Fixes #123"

# Review, approve, merge
bb pr view 42
bb pr approve 42
bb pr merge 42 --strategy squash

# Monitor pipelines
bb ci list
bb ci logs 15

Authentication

bb supports three auth methods:

| Method | How to create | Auth type | |--------|--------------|-----------| | App Password | Personal settings > App passwords | Basic Auth | | Atlassian API Token | manage.atlassian.com > API tokens | Basic Auth (auto-detected via ATATT prefix) | | OAuth / Access Token | Workspace/Repo/Project settings > Access tokens | Bearer |

# Interactive
bb auth login

# Non-interactive
bb auth login -u [email protected] -t YOUR_TOKEN

# Environment variable (takes precedence)
export BB_TOKEN=your-token

# Verify
bb auth status

Credentials stored in ~/.config/bb-cli/config.json (mode 0600).

Commands

Pull Requests

bb pr list                         # List open PRs
bb pr create                       # Create PR (interactive)
bb pr view <id>                    # View PR details
bb pr diff <id>                    # View diff
bb pr comments <id>                # Read comments
bb pr comment <id> -m "LGTM"      # Add comment
bb pr approve <id>                 # Approve
bb pr unapprove <id>               # Remove approval
bb pr merge <id>                   # Merge
bb pr decline <id>                 # Close without merging
bb pr checkout <id>                # Checkout branch locally
bb pr update <id> --title "New"    # Update PR fields

Pipelines

Aliased as both bb pipeline and bb ci:

bb ci list                         # List recent pipelines
bb ci view <build#>                # View steps and status
bb ci run                          # Trigger pipeline
bb ci run -b main --pattern deploy # Trigger custom pipeline
bb ci stop <build#>                # Stop running pipeline
bb ci logs <build#>                # View all step logs
bb ci logs <build#> -s "Build"     # View specific step

Raw API

Escape hatch for any Bitbucket REST API v2 endpoint:

bb api /repositories/workspace/repo
bb api --method POST /path --field title="Bug"
bb api --paginate /path

Common Flags

| Flag | Description | |------|-------------| | -R, --repo workspace/repo | Specify repository (auto-detected from git remote) | | -F, --output json | JSON output for scripting | | -p, --page N | Page number | | -P, --per-page N | Items per page | | -w, --web | Open in browser |

License

MIT