| name | bkt |
| version | 0.28.1 |
| description | Bitbucket CLI for Data Center and Cloud. Use when users need to manage repositories, pull requests, branches, issues, webhooks, or pipelines in Bitbucket. Triggers include "bitbucket", "bkt", "pull request", "PR", "repo list", "branch create", "Bitbucket Data Center", "Bitbucket Cloud", "keyring timeout". |
| metadata | {"short-description":"Bitbucket CLI for repos, PRs, branches","compatibility":"claude-code, codex-cli"} |
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:
| 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:
bkt auth login https://bitbucket.example.com --username alice --token <PAT>
bkt auth login https://bitbucket.org --kind cloud --web
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:
bkt context create dc-prod --host bitbucket.example.com --project ABC --set-active
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
bkt pr approve 42
bkt pr merge 42
Checkout a colleague's PR locally
bkt pr checkout 42
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:
| 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
