eduardoborges/dotfiles/bkt

Bitbucket CLI (bkt)

bkt is a unified CLI for Bitbucket Data Center and Bitbucket Cloud. It mirrors gh ergonomics and provides structured JSON/YAML output for automation.

Before You Start

1. Verify installation — always check before running any bkt command:

bkt --version

If not installed:

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:

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 '.pull_requests[].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:

References

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

<!-- auto-generated by cmd/docgen — do not edit below this line -->

• 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)
• mcp — Model Context Protocol server for agents
• 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

<!-- end auto-generated -->