Bitbucket CLI (bb)

A comprehensive command-line interface for Bitbucket Cloud, designed for developers and AI agents.

Table of Contents

• Features
• Installation
• Quick Start
• Authentication
• Commands
  • Repository Management
  • Pull Requests
  • Issues
  • Pipelines
  • Branches & Commits
  • Workspaces & Projects
  • Webhooks
  • Configuration
  • Raw API Access
• Configuration
• Output Formats
• Environment Variables
• Examples
• Development
• Contributing
• License

Features

Core Features:

• Browser-based OAuth authentication (like GitHub CLI)
• Multiple authentication methods (OAuth, API tokens, repository tokens)
• Comprehensive Bitbucket Cloud API coverage
• AI-agent friendly (JSON output, stdin support)
• Beautiful terminal UI with colors and tables
• Secure credential storage in OS keychain
• Fast and efficient (written in Rust)
• Auto-detection of workspace/repo from git remote

Supported Operations:

• Repositories (create, list, view, clone, fork, delete)
• Pull Requests (create, list, view, merge, approve, comment)
• Issues (create, list, view, update, comment)
• Pipelines (view, trigger, monitor)
• Branches (list, create, delete)
• Commits (view, compare)
• Workspaces & Projects
• Webhooks
• File/source browsing
• And much more!

Installation

From Source (Recommended)

# Clone the repository
git clone https://github.com/datlechin/bitbucket-cli.git
cd bitbucket-cli

# Build and install
cargo install --path .

# Verify installation
bb --version

Using Cargo

cargo install bitbucket-cli

Binary Releases

Download pre-built binaries from the Releases page.

Quick Start

1. Authenticate

Option A: Browser-based authentication (Recommended)

# Simply run - OAuth credentials are built-in!
bb auth login --with-web

Your browser will open automatically. Click "Grant access" and you're done!

Option B: API Token (Also Easy)

bb auth login --with-api-token
# Enter your Atlassian account email and API token

Option C: Interactive Setup

bb auth setup
# Follow the guided setup wizard

2. Configure Default Workspace

bb config set default_workspace my-workspace

3. Start Using!

# List your repositories
bb repo list

# View pull requests
bb pr list

# Check pipeline status
bb pipeline list

Authentication

Bitbucket CLI supports multiple authentication methods:

1. OAuth 2.0 (Browser-based)

Like GitHub CLI - authenticate via your web browser. No setup required!

Login:

bb auth login --with-web

That's it! The CLI has built-in OAuth credentials. Your browser opens, you click "Grant access", and you're authenticated.

2. API Token (Recommended)

Most secure and easy to set up.

Create API Token:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Select scopes: account, repository, pullrequest, issue, pipeline, webhook

Login:

bb auth login --with-api-token

3. Repository Access Token

Limited to a specific repository.

bb auth login
# Select "Repository Access Token"

4. Workspace Access Token

Limited to a specific workspace.

bb auth login
# Select "Workspace Access Token"

Authentication Management

# Check authentication status
bb auth status

# Refresh OAuth token (for OAuth auth)
bb auth refresh

# Logout
bb auth logout

Commands

Repository Management

List Repositories

# List repositories in configured workspace
bb repo list

# List repositories in specific workspace
bb repo list -W myworkspace

# List with JSON output
bb repo list -o json

# Filter by name
bb repo list --name myrepo

View Repository

# View repository details
bb repo view myrepo

# View specific workspace's repository
bb repo view -W myworkspace myrepo

# JSON output
bb repo view myrepo -o json

Create Repository

# Create a repository
bb repo create my-new-repo

# Create with description
bb repo create my-new-repo --description "My awesome project"

# Create private repository
bb repo create my-new-repo --private

# Create with specific language
bb repo create my-new-repo --language python

Clone Repository

# Clone via HTTPS
bb repo clone myrepo

# Clone via SSH
bb repo clone myrepo --ssh

# Clone to specific directory
bb repo clone myrepo --path /path/to/dir

Fork Repository

# Fork a repository
bb repo fork original-owner/original-repo

# Fork to specific workspace
bb repo fork original-owner/original-repo -W my-workspace

Delete Repository

# Delete repository (with confirmation)
bb repo delete myrepo

# Force delete (no confirmation)
bb repo delete myrepo --yes

Pull Requests

List Pull Requests

# List all pull requests
bb pr list

# List open PRs
bb pr list --state OPEN

# List merged PRs
bb pr list --state MERGED

# List PRs for specific repository
bb pr list -R myrepo

# List with specific author
bb pr list --author username

View Pull Request

# View PR details
bb pr view 123

# View with comments
bb pr view 123 --with-comments

# JSON output
bb pr view 123 -o json

Create Pull Request

# Create PR (interactive)
bb pr create

# Create with title and description
bb pr create --title "Add new feature" --description "This PR adds..."

# Create from branch
bb pr create --source feature-branch --destination main

# Create with reviewers
bb pr create --reviewer user1 --reviewer user2

# Close PR after merge
bb pr create --close-source-branch

Merge Pull Request

# Merge PR
bb pr merge 123

# Merge with merge commit
bb pr merge 123 --strategy merge

# Squash merge
bb pr merge 123 --strategy squash

# Fast-forward merge
bb pr merge 123 --strategy fast-forward

# Close source branch after merge
bb pr merge 123 --close-source-branch

# Add merge message
bb pr merge 123 --message "Merged feature X"

Approve/Decline Pull Request

# Approve PR
bb pr approve 123

# Decline PR
bb pr decline 123

# Request changes
bb pr request-changes 123

Comment on Pull Request

# Add comment
bb pr comment 123 --body "Looks good to me!"

# Add inline comment
bb pr comment 123 --body "Fix this" --file src/main.rs --line 42

Diff Pull Request

# View PR diff
bb pr diff 123

# View specific file
bb pr diff 123 --file src/main.rs

Issues

List Issues

# List all issues
bb issue list

# List open issues
bb issue list --state open

# List closed issues
bb issue list --state closed

# List issues assigned to you
bb issue list --assignee @me

# List issues by reporter
bb issue list --reporter username

View Issue

# View issue details
bb issue view 42

# With comments
bb issue view 42 --with-comments

Create Issue

# Create issue (interactive)
bb issue create

# Create with title and description
bb issue create --title "Bug: App crashes" --description "Steps to reproduce..."

# Create with priority
bb issue create --title "Fix typo" --priority minor

# Assign to user
bb issue create --title "New feature" --assignee username

# Set type
bb issue create --title "Enhancement" --kind enhancement

Update Issue

# Update issue title
bb issue update 42 --title "New title"

# Change state
bb issue update 42 --state resolved

# Change priority
bb issue update 42 --priority major

# Assign to user
bb issue update 42 --assignee username

Comment on Issue

bb issue comment 42 --body "Thanks for reporting!"

Close/Reopen Issue

# Close issue
bb issue close 42

# Reopen issue
bb issue reopen 42

Pipelines

List Pipelines

# List all pipelines
bb pipeline list

# List recent pipelines
bb pipeline list --limit 10

# List for specific branch
bb pipeline list --branch main

# List with specific status
bb pipeline list --status SUCCESSFUL
bb pipeline list --status FAILED
bb pipeline list --status IN_PROGRESS

View Pipeline

# View pipeline details
bb pipeline view {uuid}

# View with steps
bb pipeline view {uuid} --with-steps

# View logs
bb pipeline view {uuid} --with-logs

Trigger Pipeline

# Trigger pipeline for branch
bb pipeline run --branch main

# Trigger with custom variables
bb pipeline run --branch main --variable KEY1=VALUE1 --variable KEY2=VALUE2

# Trigger specific pipeline
bb pipeline run --branch main --pipeline custom-pipeline.yml

Stop Pipeline

bb pipeline stop {uuid}

Branches & Commits

List Branches

# List all branches
bb branch list

# Filter by name
bb branch list --name feature

# List with commit info
bb branch list --with-commits

Create Branch

# Create branch from main
bb branch create feature-branch --from main

# Create from specific commit
bb branch create hotfix --from abc123

Delete Branch

# Delete branch
bb branch delete feature-branch

# Force delete
bb branch delete feature-branch --force

List Commits

# List commits
bb commit list

# List for specific branch
bb commit list --branch main

# List with limit
bb commit list --limit 20

# List by author
bb commit list --author username

View Commit

# View commit details
bb commit view abc123

# View with diff
bb commit view abc123 --with-diff

# View specific file in commit
bb commit view abc123 --file src/main.rs

Workspaces & Projects

List Workspaces

# List your workspaces
bb workspace list

# View workspace details
bb workspace view myworkspace

List Projects

# List projects in workspace
bb project list -W myworkspace

# View project details
bb project view PROJ -W myworkspace

Webhooks

List Webhooks

# List repository webhooks
bb webhook list -R myrepo

# List workspace webhooks
bb webhook list -W myworkspace

Create Webhook

# Create repository webhook
bb webhook create -R myrepo \
  --url https://example.com/hook \
  --events repo:push \
  --events pullrequest:created

# Create with description
bb webhook create -R myrepo \
  --url https://example.com/hook \
  --description "CI/CD webhook"

Delete Webhook

bb webhook delete {uuid} -R myrepo

Configuration

View Configuration

bb config show

Set Configuration

# Set default workspace
bb config set default_workspace myworkspace

# Set default repository
bb config set default_repository myrepo

# Set output format
bb config set output_format json

# Set page size
bb config set page_size 50

# Set OAuth credentials
bb config set oauth_client_id YOUR_CLIENT_ID
bb config set oauth_client_secret YOUR_CLIENT_SECRET

# Set editor
bb config set editor vim

# Set pager
bb config set pager less

Get Configuration

bb config get default_workspace

Reset Configuration

bb config reset

View Config File Path

bb config path

Raw API Access

For advanced users and AI agents.

# GET request
bb api /repositories/{workspace}/{repo}

# POST request
bb api -X POST /repositories/{workspace}/{repo}/issues \
  --data '{"title":"Bug report"}'

# With custom headers
bb api /user --header "X-Custom: value"

# Paginated request
bb api /repositories/{workspace} --paginate

Configuration

Configuration File

Location: ~/.config/bitbucket-cli/config.toml

default_workspace = "myworkspace"
default_repository = "myrepo"
output_format = "table"
api_url = "https://api.bitbucket.org/2.0"
color = true
page_size = 25
editor = "vim"
pager = "less"
oauth_client_id = "your-client-id"
oauth_client_secret = "your-client-secret"

[aliases]
prs = "pr list --state OPEN"
repos = "repo list"

Credential Storage

Credentials are stored securely in your OS keychain:

• macOS: Keychain
• Windows: Credential Manager
• Linux: Secret Service (gnome-keyring, kwallet, etc.)

Output Formats

Bitbucket CLI supports multiple output formats:

# Table (default) - Human-readable
bb repo list

# JSON - Machine parsing
bb repo list -o json

# Pretty JSON - Readable JSON
bb repo list -o json-pretty

# YAML
bb repo list -o yaml

# TSV - Tab-separated values
bb repo list -o tsv

# CSV - Comma-separated values
bb repo list -o csv

# Quiet - IDs only
bb repo list -o quiet

Environment Variables

Authentication

# API Token
export BITBUCKET_EMAIL="your@email.com"
export BITBUCKET_API_TOKEN="your-token"

# OAuth Access Token
export BITBUCKET_ACCESS_TOKEN="token"
export BITBUCKET_REFRESH_TOKEN="refresh-token"

# Repository Token
export BITBUCKET_REPO_TOKEN="token"

# Workspace Token
export BITBUCKET_WORKSPACE_TOKEN="token"

# OAuth Credentials (for browser auth)
export BITBUCKET_CLI_OAUTH_CLIENT_ID="client-id"
export BITBUCKET_CLI_OAUTH_CLIENT_SECRET="client-secret"

Configuration

# Workspace/Repository
export BITBUCKET_WORKSPACE="myworkspace"
export BITBUCKET_REPO="myrepo"

Examples

Daily Workflow

# Morning: Check what's new
bb pr list --state OPEN
bb issue list --assignee @me
bb pipeline list --limit 5

# Create a feature
git checkout -b feature-xyz
# ... make changes ...
git push origin feature-xyz
bb pr create --title "Add feature XYZ" --reviewer teammate

# Monitor PR
bb pr view 123
bb pr diff 123

# Approve teammate's PR
bb pr approve 124
bb pr merge 124

# Check pipelines
bb pipeline list --branch main

Repository Management

# Create new project
bb repo create my-project --description "My awesome project" --private
cd my-project
git init
git remote add origin $(bb repo view my-project -o json | jq -r '.clone_url')

# Fork and clone
bb repo fork upstream/awesome-lib
bb repo clone awesome-lib

Issue Tracking

# Create bug report
bb issue create \
  --title "App crashes on startup" \
  --description "Steps: 1. Open app 2. Crash" \
  --priority critical \
  --kind bug

# Track progress
bb issue list --state open
bb issue update 42 --state in-progress
bb issue comment 42 --body "Working on this"
bb issue close 42

CI/CD Monitoring

# Watch pipeline
watch -n 5 'bb pipeline list --branch main --limit 1'

# Trigger build
bb pipeline run --branch main

# Check logs
bb pipeline view {uuid} --with-logs

Bulk Operations (with jq)

# Get all open PRs as JSON
bb pr list --state OPEN -o json | jq

# Extract PR titles
bb pr list -o json | jq -r '.values[].title'

# Get all repos with SSH URLs
bb repo list -o json | jq -r '.values[] | "\(.name): \(.links.clone[] | select(.name=="ssh") | .href)"'

# List all failed pipelines
bb pipeline list -o json | jq -r '.values[] | select(.state.result.name=="FAILED") | .uuid'

Development

Build from Source

# Clone repository
git clone https://github.com/datlechin/bitbucket-cli.git
cd bitbucket-cli

# Build
cargo build --release

# Run tests
cargo test

# Run locally
cargo run -- --help

Project Structure

bitbucket-cli/
├── src/
│   ├── api/            # API client and OAuth
│   ├── commands/       # CLI commands
│   ├── config/         # Configuration and auth
│   ├── models/         # Data models
│   ├── output/         # Output formatting
│   └── main.rs         # Entry point
├── Cargo.toml
├── README.md

Technologies

• Language: Rust 🦀
• CLI Framework: clap
• HTTP Client: reqwest
• Async Runtime: tokio
• Serialization: serde
• Credential Storage: keyring

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: cargo test
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

Guidelines

• Follow Rust best practices
• Add tests for new features
• Update documentation
• Keep commits atomic and descriptive

Roadmap

• GitHub CLI-style aliases (bb pr checkout)
• Interactive TUI mode
• Code search
• Snippets management
• Team/permissions management
• Repository settings
• Deployment environments
• SSH key management
• GPG key support
• Advanced git operations

FAQ

Q: How is this different from Atlassian's official CLI?

A: Bitbucket CLI (bb) is designed to be similar to GitHub CLI (gh):

• More user-friendly interface
• Browser-based authentication
• Better output formatting
• AI-agent optimized
• Comprehensive API coverage

Q: Can I use this with Bitbucket Server/Data Center?

A: Currently, only Bitbucket Cloud is supported. Server/Data Center support is on the roadmap.

Q: Is my authentication secure?

A: Yes! Credentials are stored in your OS keychain using industry-standard security practices.

Q: Can I use this in CI/CD?

A: Yes! Use API tokens and JSON output:

export BITBUCKET_EMAIL="ci@example.com"
export BITBUCKET_API_TOKEN="$CI_TOKEN"
bb repo list -o json

Q: Why Rust?

A: Rust provides:

• Fast performance
• Memory safety
• Excellent async support
• Great CLI libraries
• Single-binary distribution

Support

• Documentation
• Issue Tracker
• Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by GitHub CLI
• Built with ❤️ by the Bitbucket CLI community
• Powered by Bitbucket Cloud API

Happy coding!

For more information, visit https://github.com/datlechin/bitbucket-cli