README

BB CLI

A modern Bitbucket Cloud CLI built with Laravel Zero.

Features

Pull Requests - Create, list, approve, merge, decline, diff, and manage PRs
Pipelines - Trigger, monitor, and wait for CI/CD pipelines
Branches - List and filter branches by name or author
Environments - Manage deployment environments and variables
Authentication - Secure credential storage with API tokens
Browse - Open repositories in the browser from the terminal
Auto-detection - Automatically detects workspace/repo from git remote

Requirements

PHP 8.2+
Git

Installation

composer global require jeffersongoncalves/bb-cli

Or clone and build locally:

git clone https://github.com/jeffersongoncalves/bb-cli.git
cd bb-cli
composer install
php bb app:build bb

Getting Started

1. Create a Bitbucket API Token

Go to your Bitbucket Account settings > Security > API tokens
Click Create API token with scopes
Name the token (e.g. bb-cli) and set an expiry date
Select Bitbucket as the app and grant the following permissions:

Note: In Bitbucket API tokens, Write does not imply Read — each permission must be granted separately.

Scope	Permission	Scope ID	Required for
Repositories	Read	`read:repository:bitbucket`	List branches, browse source code
Pull Requests	Read	`read:pullrequest:bitbucket`	View and list PRs, diffs, commits
Pull Requests	Write	`write:pullrequest:bitbucket`	Create, approve, merge, decline PRs
Pipelines	Read	`read:pipeline:bitbucket`	View pipeline status and logs
Pipelines	Write	`write:pipeline:bitbucket`	Trigger and stop pipelines
Pipelines	Admin	`admin:pipeline:bitbucket`	Manage environment variables

Click Create token and copy it immediately — it will only be shown once

Migrating from App Passwords? API tokens are the long-term replacement for App Passwords. Simply run bb auth:save again with your new API token — existing config.json files using the old app_password format are still supported.

Important: API tokens require your Atlassian account email for API authentication, not your Bitbucket username. Your email can be found in Bitbucket under Personal settings > Email Aliases.

2. Save your credentials

bb auth:save

You will be prompted for your Atlassian account email and API token.

3. Verify authentication

bb auth:show

4. Start using commands

bb pr:list
bb pipeline:latest
bb browse

All commands auto-detect the repository from your git remote. Use --project=owner/repo to override.

Commands

Authentication

Command	Description
`auth:save`	Save Bitbucket credentials (email and API token)
`auth:show`	Display saved credentials

Pull Requests

Command	Description
`pr:list`	List pull requests (filter by `--state` and `--destination`)
`pr:create <source> [destination]`	Create a new pull request
`pr:approve <id>`	Approve a PR (use `0` to approve all open PRs)
`pr:unapprove <id>`	Remove approval from a PR
`pr:request-changes <id>`	Request changes on a PR
`pr:unrequest-changes <id>`	Remove change request from a PR
`pr:merge <id>`	Merge a PR (`--strategy=merge_commit\|squash\|fast_forward`)
`pr:decline <id>`	Decline a PR
`pr:commits <id>`	List commits in a PR
`pr:diff <id>`	Display the diff of a PR
`pr:files <id>`	List changed files in a PR

Pipelines

Command	Description
`pipeline:latest`	Get the latest pipeline status
`pipeline:get <id>`	Get pipeline details by UUID or build number
`pipeline:run <branch>`	Trigger a pipeline for a branch
`pipeline:custom <branch> <pattern>`	Trigger a custom pipeline
`pipeline:wait [id]`	Wait for a pipeline to complete with live status

Branches

Command	Description
`branch:list`	List all repository branches
`branch:name <pattern>`	Filter branches by name pattern
`branch:user <name>`	List branches by a specific author

Environments

Command	Description
`env:list`	List deployment environments
`env:variables <environment>`	List variables for an environment
`env:create-variable <environment>`	Create an environment variable
`env:update-variable <environment>`	Update an environment variable

Browse

Command	Description
`browse`	Open repository in the browser
`browse:show`	Display repository URL

Global Options

Option	Description
`--project=owner/repo`	Override auto-detected repository
`--help`	Show command help
`-v`	Verbose output

Development

# Install dependencies
composer install

# Run tests
composer test

# Run tests only
composer test:unit

# Code formatting
composer lint

# Static analysis
composer phpstan

License

BB CLI is open-source software licensed under the MIT license.

jeffersongoncalves / bb-cli

Maintainers

Details