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/

With `go install`

# Requires Go 1.25+

# Install a specific version (recommended — pin to a release)
go install github.com/TwoStone/bitbucket-cli/cmd/bitbucket-cli@v1.2.1 # x-release-please-version

# Or install the latest release
go install github.com/TwoStone/bitbucket-cli/cmd/bitbucket-cli@latest

Make sure $(go env GOPATH)/bin is on your PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Build from a local checkout

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

Commit to main using Conventional Commits
release-please opens (or updates) a "Release PR" with the bumped version and a generated CHANGELOG.md
Merge the Release PR — release-please creates the git tag automatically
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/config.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/config.yaml`)
`-v`, `--verbose`	Enable verbose output — logs server URL resolution and every HTTP request/response (status only; Authorization header is redacted)

Server URL resolution

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

--server flag
Parsed from the origin remote of the current git repo
(https://bitbucket.example.com/scm/PRJ/repo.git → https://bitbucket.example.com)
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 list --json url,default,authenticated  # JSON output
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 (default: up to 30)
bitbucket projects list                           # explicit alias for the command above
bitbucket projects --limit 100                    # increase limit
bitbucket projects --json                         # full JSON output
bitbucket projects --json key,name                # select specific fields
bitbucket projects --jq '.[].key'                 # filter with jq expression
bitbucket projects clone <projectKey>             # clone all repos into current directory
bitbucket projects clone <projectKey> -d ~/work   # clone into a specific directory

Available JSON fields: key, id, name, description, public, type, links

Repositories

# List repositories
bitbucket repo                                    # list all repos (across all projects, default: 30)
bitbucket repo <projectKey>                       # list repos in a project
bitbucket repo list                               # explicit alias for the command above
bitbucket repo list <projectKey>
bitbucket repo --archived true                    # show only archived repos
bitbucket repo --visibility public                # filter by visibility: public or private
bitbucket repo --name myapp                       # filter by name substring
bitbucket repo --limit 50                         # fetch up to 50 results
bitbucket repo --json                             # full JSON output
bitbucket repo --json slug,name,project           # select specific fields
bitbucket repo --web                              # open repos in browser

# View a single repository
bitbucket repo view                               # auto-detected from git remote
bitbucket repo view MY-PRJ my-service
bitbucket repo view --web                         # open in browser
bitbucket repo view --json

# Fork a repository
bitbucket repo fork                               # fork current repo (auto-detected)
bitbucket repo fork MY-PRJ my-service --target-project ~username

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

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

# Edit — only the flags you pass are changed
bitbucket repo edit                               # auto-detected from git remote
bitbucket repo edit MY-PRJ my-service --description "new description"
bitbucket repo edit MY-PRJ my-service --default-branch develop --public=false

# Delete — asks you to type <project>/<repo> to confirm
bitbucket repo delete MY-PRJ my-service
bitbucket repo delete MY-PRJ my-service --yes      # skip the confirmation prompt

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

Available JSON fields: slug, id, name, description, project, public, state, archived, defaultBranch, links

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, up to 30)
bitbucket pr list
bitbucket pr list --state MERGED
bitbucket pr list --state ALL
bitbucket pr list --at main                       # filter by target branch
bitbucket pr list --direction OUTGOING            # INCOMING or OUTGOING
bitbucket pr list --draft true                    # draft PRs only
bitbucket pr list --filter "WIP"                  # text search (title/description)
bitbucket pr list --limit 50
bitbucket pr list --json                          # full JSON output
bitbucket pr list --json id,title,state,author    # select specific fields
bitbucket pr list --jq '.[] | select(.state=="OPEN") | .title'
bitbucket pr list --web                           # open PRs in browser

# View a PR
bitbucket pr view 42
bitbucket pr view 42 --json
bitbucket pr view 42 --web                        # open in browser

# View a PR's diff
bitbucket pr diff 42

# View build/CI status
bitbucket pr checks 42
bitbucket pr checks 42 --json

# 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

Available JSON fields: id, title, state, author, fromRef, toRef, createdDate, updatedDate, description, reviewers, draft, links

Branches and Tags

# Branches — auto-detected repo or explicit
bitbucket repo branch
bitbucket repo branch MY-PRJ my-service
bitbucket repo branch --filter feature/           # API-level branch name filter
bitbucket repo branch --limit 50
bitbucket repo branch --json                      # full JSON output
bitbucket repo branch --json displayId,default
bitbucket repo branch --web                       # open repo in browser

# Tags
bitbucket repo tag list
bitbucket repo tag list MY-PRJ my-service
bitbucket repo tag list --limit 20
bitbucket repo tag list --json                    # full JSON output
bitbucket repo tag list --web                     # open repo in browser
bitbucket repo tag create v1.2.3 <commit-sha>
bitbucket repo tag create v1.2.3 <commit-sha> --message "Release v1.2.3"

Output Flags

Most list and view commands support the following output flags, inspired by gh:

Flag	Description
`--json [fields]`	Output JSON. Optionally comma-separate field names to select (e.g. `--json id,title`).
`--jq <expr>`	Filter JSON output using a jq expression. Implies `--json`.
`--template <tmpl>`	Format JSON output using a Go template. Implies `--json`.
`--limit <n>`	Maximum number of items to fetch (default: 30). List commands only.
`--web`	Open the result(s) in the web browser. List/view commands only.

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.

Integration Tests

Integration tests spin up a real Bitbucket Data Center 9 instance via testcontainers-go and exercise the CLI against it end-to-end.

Running

make integration-test

This runs go test -tags=integration -timeout=15m -v ./....

Requirements

Docker must be running (Docker Desktop, Colima, or any compatible daemon)
No manual setup is needed — the container is started, configured, and torn down automatically

What they test

internal/bitbucket/service_integration_test.go — exercises every Service method against a live Bitbucket instance (projects, repositories, branches, pull requests, diffs)
internal/integration/cli_test.go — exercises CLI commands (projects, repo, repo branch, pr list, pr view, pr diff) through the full cobra command stack

License

The tests use the publicly available Atlassian timebomb license intended for test and development use. No secrets are required.

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.

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
.github		.github
cmd/bitbucket-cli		cmd/bitbucket-cli
internal		internal
tools		tools
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
release-please-config.json		release-please-config.json

Navigation Menu

Repository files navigation

bitbucket-cli

Installation

Pre-built binaries (recommended)

With `go install`

Build from a local checkout

Releasing

How it works

Commit prefix → version bump

Getting Started

Configuration

Global flags

Server URL resolution

Commands

Authentication

Server Management

Projects

Repositories

Pull Requests

Branches and Tags

Output Flags

Shell Completion

Version

Authentication Details

Integration Tests

Running

Requirements

What they test

License

Regenerating the API Client

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

bitbucket-cli

Installation

Pre-built binaries (recommended)

With go install

Build from a local checkout

Releasing

How it works

Commit prefix → version bump

Getting Started

Configuration

Global flags

Server URL resolution

Commands

Authentication

Server Management

Projects

Repositories

Pull Requests

Branches and Tags

Output Flags

Shell Completion

Version

Authentication Details

Integration Tests

Running

Requirements

What they test

License

Regenerating the API Client

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

With `go install`