bb-cli

Bitbucket CLI is a command line interface for interacting with Bitbucket.

Installation

macOS

To install the latest version, run:

curl -fsSL https://raw.githubusercontent.com/tmaffia/bitbucket-cli/main/scripts/install.sh | sh

Features

• Authentication: Secure login using Bitbucket API Tokens (stored in system keyring).
• Pull Requests: List, view, diff, and comment on pull requests.
• Repository Browsing: List files, view file contents, and open repos in browser.
• Code Search: Search code across your workspace.
• Configuration: Manage multiple profiles and default settings.
• Git Integration: Auto-detects repository and branch from current directory.

Configuration and Auth Setup

1. Create an API Token

To use this CLI, you need an API Token from your Atlassian account:

1. Log in to id.atlassian.com.
2. Click Create API token.
3. Give it a label (e.g., "bb-cli").
4. Click Create.
5. Copy the generated token. You will need this for the CLI login.

2. Installation and Setup

1. Install the binary:

   macOS / Linux: Use the install script to download the pre-built binary:

   curl -fsSL https://raw.githubusercontent.com/tmaffia/bitbucket-cli/main/scripts/install.sh | sh

   Windows: Clone the repository and install via Cargo:

   cargo install --path .

2. Authenticate with your Bitbucket account:

   bb auth login

   • Enter your Bitbucket email.
   • Enter the API Token you generated in step 1.

3. Initialize the configuration in your bitbucket repository folder:

   bb config init

Global Flags

• --json: Output results in JSON format (available for list commands).

Usage

Repositories

List repositories in your workspace:

bb repo list

# List with a custom limit (default is 100)
bb repo list --limit 20

List files and directories:

# List root directory
bb repo tree

# List specific path
bb repo tree src/commands/

# List on a specific branch
bb repo tree --ref main

View file contents:

bb repo view README.md
bb repo view src/main.rs --ref develop

Browse

Open repository in browser:

# Current repository
bb browse

# Specific repository
bb browse myworkspace/myrepo

Search

Search code across your workspace:

bb search code "function_name"

# Filter by extension
bb search code "error" --extension rs

# Filter by repository
bb search code "TODO" --repo myrepo

# Limit results
bb search code "panic" --limit 10

Pull Requests

List pull requests:

bb pr list

View a pull request (auto-detected from branch or by ID):

bb pr view
bb pr view 123

View Diff with Filtering:

You can filter the diff by file patterns or size.

Inferred Context (Current Branch):

# Filter by file extension
bb pr diff "*.rs"

# Filter by directory
bb pr diff src/commands/

Manual Context (Explicit ID):

# Filter by specific file for PR #123
bb pr diff 123 src/main.rs

# Skip large files for PR #123
bb pr diff 123 --max-diff-size 100

Review a Pull Request:

Start an interactive review or submit immediately with flags.

Inferred Context (Current Branch):

# Interactive mode
bb pr review

# Approve immediately
bb pr review --approve

Manual Context (Explicit ID):

# Interactive mode for PR #123
bb pr review 123

# Request changes for PR #123
bb pr review 123 --request-changes

# Comment on PR #123
bb pr review 123 --comment --body "Great work!"

Override Repository:

You can run any command against a specific repository using -R:

# List PRs in a different repo
bb pr list -R my-workspace/other-repo

# View PR #123 in a different repo
bb pr view 123 -R my-workspace/other-repo

Configuration

View your current configuration (active profile and local overrides):

bb config list

Set a configuration value:

# Set the active profile (user)
bb config set user <PROFILE_NAME>

# Set workspace for the default profile
bb config set profile.default.workspace <WORKSPACE_NAME>

Development

For contributing to this repository, you can set up the pre-push hooks (recommended):

cp scripts/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-push