Platform	Command
macOS/Linux	`brew install avivsinai/tap/bitbucket-cli`
Windows	`scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket && scoop install bitbucket-cli`
Go	`go install github.com/avivsinai/bitbucket-cli/cmd/bkt@latest`
Binary	Download from GitHub Releases

2. Check authentication — most commands require an active session:

bkt auth status

Bitbucket Cloud Token Requirements:

Create an "API token with scopes" (not a general API token)
Select Bitbucket as the application
Required scope: Account: Read (read:user:bitbucket)
Additional scopes as needed: Repositories, Pull requests, Issues

For config-free use in containers and CI pipelines, see headless authentication.

If not authenticated, log in:

# Data Center (PAT-based)
bkt auth login https://bitbucket.example.com --username alice --token <PAT>

# Bitbucket Cloud — OAuth (official binaries open browser out of the box)
bkt auth login https://bitbucket.org --kind cloud --web

# Bitbucket Cloud — API token (--web-token opens Atlassian's token creation page)
bkt auth login https://bitbucket.org --kind cloud --web-token

For source and Nix builds, set BKT_OAUTH_CLIENT_ID and BKT_OAUTH_CLIENT_SECRET env vars before running --web.

3. Set up a context — contexts bind a host to a project/workspace and optional default repo, so you don't repeat flags on every command:

# Data Center
bkt context create dc-prod --host bitbucket.example.com --project ABC --set-active

# Cloud
bkt context create cloud-team --host bitbucket.org --workspace myteam --set-active

Platform Awareness

Some commands are Data Center only or Cloud only — check the command reference for *(DC)* and *(Cloud)* badges. Key splits:

Feature	Data Center	Cloud
Pull requests	yes	yes
Repositories	yes	yes
Branches (list)	yes	yes
Branches (create/delete/protect)	yes	—
Issues	—	yes
Pipelines	—	yes
Permissions	yes	—
Webhooks	yes	yes
Auto-merge, tasks, reactions	yes	—
Variables	—	yes

When a user's context is DC, do not suggest Cloud-only commands (and vice versa). If the platform is unknown, ask or check with bkt auth status.

Common Workflows

Create a PR from the current branch

bkt pr create --title "feat: add caching" --target main

Source branch, title, and target default to sensible values from git state. Add --draft for work-in-progress, --reviewer alice to request review.

Review cycle

bkt pr checks 42 --wait          # Wait for CI to pass
bkt pr approve 42                # Approve
bkt pr merge 42                  # Merge (closes source branch by default)

Checkout a colleague's PR locally

bkt pr checkout 42               # Creates pr/42 branch

Structured output for scripting

All commands support --json, --yaml, --jq, and --template:

bkt pr list --mine --json | jq '.[].title'

Raw API escape hatch

For endpoints without a dedicated command:

bkt api /rest/api/1.0/projects --param limit=100 --json

Global Flags

Every command accepts these inherited flags:

Flag	Short	Purpose
`--context`	`-c`	Use a specific named context
`--json`		JSON output
`--yaml`		YAML output
`--jq`		Apply a jq expression (requires `--json`)
`--template`		Render with Go template

References

headless / env vars — Config-free CI/container auth (BKT_TOKEN, BKT_HOST) and full env var reference

admin — Administrative operations for Bitbucket (DC)
auth — Manage Bitbucket authentication credentials
branch — Inspect and manage branches
commit — Work with commits
context — Manage Bitbucket CLI contexts
extension — Manage bkt CLI extensions
issue — Work with Bitbucket Cloud issues (Cloud)
perms — Manage Bitbucket permissions (DC)
pipeline — Run and inspect Bitbucket Cloud pipelines (Cloud)
pr — Manage pull requests
project — Work with Bitbucket projects (DC)
repo — Work with Bitbucket repositories
status — Inspect commit and pull request statuses
variable — Manage pipeline variables (Cloud)
webhook — Manage Bitbucket webhooks
other — api

bkt

Bitbucket CLI (bkt)

Before You Start