bitbucket-cli

README

bitbucket-cli

A CLI for Bitbucket Data Center — folder-aware and with credentials stored securely in the OS keychain, inspired by gh and glab.

Installation

Pre-built binaries (recommended)

Download the latest release for your platform from the GitHub Releases page.

# macOS (Apple Silicon)
curl -sL https://github.com/TwoStone/bitbucket-cli/releases/latest/download/bitbucket-cli_<version>_darwin_arm64.tar.gz | tar xz
sudo mv bitbucket-cli /usr/local/bin/

# macOS (Intel)
curl -sL https://github.com/TwoStone/bitbucket-cli/releases/latest/download/bitbucket-cli_<version>_darwin_amd64.tar.gz | tar xz
sudo mv bitbucket-cli /usr/local/bin/

# Linux (amd64)
curl -sL https://github.com/TwoStone/bitbucket-cli/releases/latest/download/bitbucket-cli_<version>_linux_amd64.tar.gz | tar xz
sudo mv bitbucket-cli /usr/local/bin/

From source

# Requires Go 1.24+
go install github.com/TwoStone/bitbucket-cli/cmd/bitbucket-cli@latest

# Or build locally
git clone https://github.com/TwoStone/bitbucket-cli.git
cd bitbucket-cli
make build        # → ./bin/bitbucket-cli
make install      # → $GOPATH/bin/bitbucket-cli

Releasing

Releases are fully automated using release-please and GoReleaser. No manual tagging is needed.

How it works

1. Commit to main using Conventional Commits
2. release-please opens (or updates) a "Release PR" with the bumped version and a generated CHANGELOG.md
3. Merge the Release PR — release-please creates the git tag automatically
4. GoReleaser fires on the new tag and publishes cross-platform binaries to GitHub Releases

Commit prefix → version bump

Prefix	Example	Bump
fix:	fix: handle empty PR list	patch (0.1.0 → 0.1.1)
feat:	feat: add pr approve command	minor (0.1.0 → 0.2.0)
feat!: or BREAKING CHANGE footer	feat!: rename config key	major (0.1.0 → 1.0.0)
chore:, docs:, ci:, test:, refactor:	—	no release

Binaries are built for Linux, macOS (Intel + Apple Silicon), and Windows.

Getting Started

# 1. Log in (token is stored in the OS keychain — never on disk)
bitbucket login https://bitbucket.example.com

# 2. Clone a repository
bitbucket repo clone MY-PROJECT my-service

# 3. Inside any cloned repo, project/repo context is auto-detected from git remote
cd my-service
bitbucket pr create --title "My feature" --head feature/x --base main

Configuration

~/.bitbucket-cli.yaml is managed automatically by login and server commands — you do not need to create it manually.

servers:
  - https://bitbucket.example.com
defaultServer: https://bitbucket.example.com

Tokens are never stored in the config file. They live in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service / pass).

Global flags

Flag	Description
--server <url>	Override server URL (skips git remote auto-detection)
--config <file>	Config file path (default ~/.bitbucket-cli.yaml)

Server URL resolution

When a command runs it picks the server in this order:

1. --server flag
2. Parsed from the origin remote of the current git repo
   (https://bitbucket.example.com/scm/PRJ/repo.git → https://bitbucket.example.com)
3. defaultServer from config

Commands

Authentication

bitbucket login                                   # prompts for server URL and token
bitbucket login https://bitbucket.example.com     # prompts for token only

bitbucket logout                                  # prompts for server to log out from
bitbucket logout https://bitbucket.example.com

Server Management

bitbucket server list                             # list servers (* = default, shows auth status)
bitbucket server default https://...             # set or show the default server
bitbucket server remove https://...              # remove server and its keychain entry

Projects

bitbucket projects                                # list all projects
bitbucket projects clone <projectKey>             # clone all repos into current directory
bitbucket projects clone <projectKey> -d ~/work   # clone into a specific directory

Repositories

bitbucket repo                                    # list all repos (across all projects)
bitbucket repo <projectKey>                       # list repos in a project

bitbucket repo clone                              # interactive — prompts for project and repo
bitbucket repo clone <projectKey> <slug>
bitbucket repo clone <projectKey> <slug> -d ~/work

bitbucket repo create <projectKey> --name <name>
bitbucket repo create <projectKey> --name <name> \
  --description "..." --default-branch main --public=false

bitbucket repo open                               # open current directory in VS Code
bitbucket repo open --editor idea                 # open in JetBrains IDE

Pull Requests

Project and repo are auto-detected from the git remote when run inside a cloned repo. Use --project / --repo to override.

# List PRs (default: open)
bitbucket pr list
bitbucket pr list --state MERGED
bitbucket pr list --state ALL

# View a PR
bitbucket pr view 42

# Check out a PR's source branch locally
bitbucket pr checkout 42

# Create a PR
bitbucket pr create \
  --title "My feature" \
  --head feature/my-branch \
  --base main \
  [--description "..."] \
  [--push]                   # push source branch first

# Approve / decline / merge
bitbucket pr approve 42
bitbucket pr decline 42
bitbucket pr merge 42

# Add a comment
bitbucket pr comment 42 --body "Looks good!"

# Explicit project/repo overrides work on all pr commands:
bitbucket pr list --project MY-PRJ --repo my-service

Branches and Tags

# Branches — auto-detected repo or explicit
bitbucket repo branch
bitbucket repo branch MY-PRJ my-service
bitbucket repo branch --filter feature/

# Tags
bitbucket repo tag list
bitbucket repo tag list MY-PRJ my-service
bitbucket repo tag create v1.2.3 <commit-sha>
bitbucket repo tag create v1.2.3 <commit-sha> --message "Release v1.2.3"

Shell Completion

# Bash
bitbucket completion bash > /usr/local/etc/bash_completion.d/bitbucket

# Zsh
bitbucket completion zsh > "${fpath[1]}/_bitbucket"

# Fish
bitbucket completion fish > ~/.config/fish/completions/bitbucket.fish

# PowerShell
bitbucket completion powershell | Out-String | Invoke-Expression

Version

bitbucket version
bitbucket version --short

Authentication Details

All REST API calls use a Bearer token:

Authorization: Bearer <token>

Git operations (clone, push) also authenticate with Bearer over HTTPS.

Generate a token in Bitbucket under Profile → Manage account → HTTP access tokens.

Regenerating the API Client

The REST API client (internal/bitbucket/client/) is generated from the official Bitbucket DC v10.2 OpenAPI spec using openapi-generator-cli 7.14.0. Java 11+ is required.

# Update the spec (optional — replace URL for a newer version)
curl -sL "https://dac-static.atlassian.com/server/bitbucket/10.2.swagger.v3.json?_v=1.637.30" \
  -o tools/bitbucket-rest.oas3.json

# Regenerate and rebuild
make generate
make build

make generate also applies patches that fix recursive type cycles in the generated code.