bbt - Bitbucket Cloud CLI Tool

Go Version CI Status License: MIT

A command-line tool for Bitbucket Cloud that brings pull requests, issues, and repositories to your terminal.

Features

• Authentication: Securely authenticate with Bitbucket Cloud using app passwords or personal access tokens
• Pull Requests: List, view, create, and merge pull requests
• Issues: List, view, and create issues
• Repositories: List and view repository information
• Auto-detection: Automatically detect workspace and repository from git remotes
• Configuration: Store authentication credentials safely in ~/.config/bbt/config.yaml

Installation

From Homebrew (macOS)

brew tap romaintb/bbt https://codeberg.org/romaintb/homebrew-bbt.git
brew install bbt

From AUR (Arch Linux)

yay -S bbt

From source

go build -o bbt
sudo cp bbt /usr/local/bin/

Usage

Authentication

First, authenticate with Bitbucket Cloud:

bbt auth login

You'll be prompted to enter:

• Bitbucket username or email
• App password or personal access token
• Default workspace (optional)

Check your authentication status:

bbt auth status

Pull Requests

List pull requests:

bbt pr list -R workspace/repo --state OPEN
bbt pr list --state MERGED
bbt pr list --state DECLINED

View a specific pull request:

bbt pr view 123 -R workspace/repo

Create a new pull request:

bbt pr create -R workspace/repo --title "Feature X" --body "Description" --head feature-branch --base main

Merge a pull request:

bbt pr merge 123 -R workspace/repo --merge-strategy merge_commit

Merge strategies: merge_commit, squash, fast_forward

Issues

List issues:

bbt issue list -R workspace/repo --state new
bbt issue list --state resolved
bbt issue list --state closed

View a specific issue:

bbt issue view 456 -R workspace/repo

Create a new issue:

bbt issue create -R workspace/repo --title "Bug title" --body "Description" --kind bug

Issue kinds: bug, enhancement, proposal, task

Repositories

List repositories in a workspace:

bbt repo list workspace-name
bbt repo list # Uses default workspace from auth config

View repository details:

bbt repo view workspace/repo-slug

Configuration

Configuration is stored in ~/.config/bbt/config.yaml:

hosts:api.bitbucket.org:username:your-usernametoken:your-app-passwordworkspace:your-workspace

You can also override the config location:

bbt --config /path/to/config.yaml pr list

Environment Variables

• BBT_HOSTNAME: Override the Bitbucket API hostname

Auto-detection

When working in a git repository, you don't need to specify -R workspace/repo for most commands. The tool will automatically detect it from your git remote:

cd my-repo
bbt pr list # Auto-detects workspace and repo from git remote

Differences from gh (GitHub CLI)

This tool follows the same design patterns as gh but adapted for Bitbucket Cloud:

• Uses workspace/repo-slug instead of owner/repo
• Pull requests use numeric IDs instead of auto-incrementing numbers
• Issue states and types are Bitbucket-specific
• Uses Bitbucket Cloud API v2.0

API Credentials

You need a Bitbucket App Password or Personal Access Token with appropriate scopes:

• account: For user profile access
• repository: For repository access
• pullrequest: For pull request management
• issue: For issue management

Generate one at: https://bitbucket.org/account/settings/app-passwords/

License

MIT