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.

Dependency Check

Before executing any bkt command, verify the CLI is installed:

bash
1bkt --version

If the command fails or bkt is not found, install it using one of these methods:

Only proceed with bkt commands after confirming installation succeeds.

Authentication

bash
1# Data Center (opens browser for PAT creation)
2bkt auth login https://bitbucket.example.com --web
3
4# Data Center (direct)
5bkt auth login https://bitbucket.example.com --username alice --token <PAT>
6
7# Bitbucket Cloud
8bkt auth login https://bitbucket.org --kind cloud --web
9
10# Check auth status
11bkt 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

Contexts

Contexts store host, project/workspace, and default repo settings:

bash
1# Create context for Data Center
2bkt context create dc-prod --host bitbucket.example.com --project ABC --set-active
3
4# Create context for Cloud
5bkt context create cloud-team --host bitbucket.org --workspace myteam --set-active
6
7# List and switch contexts
8bkt context list
9bkt context use cloud-team

Quick Command Reference

Repository Operations

bash
1bkt repo list --limit 20
2bkt repo list --workspace myteam          # Cloud workspace override
3bkt repo view platform-api
4bkt repo create data-pipeline --description "Data ingestion" --project DATA
5bkt repo browse --project DATA --repo platform-api
6bkt repo clone platform-api --ssh

Pull Request Workflows

bash
1# List and view
2bkt pr list --state OPEN --limit 10
3bkt pr list --mine                        # PRs you authored
4bkt pr view 42
5bkt pr view 42 --web                      # Open in browser
6
7# Create and edit
8bkt pr create --title "feat: cache" --source feature/cache --target main --reviewer alice
9bkt pr edit 123 --title "New title" --body "Updated description"
10
11# Review and merge
12bkt pr approve 42
13bkt pr comment 42 --text "LGTM"
14bkt pr merge 42 --message "merge: feature/cache"
15bkt pr merge 42 --strategy fast-forward
16
17# CI/build status
18bkt pr checks 42                          # Show build status
19bkt pr checks 42 --wait                   # Wait for builds to complete
20bkt pr checks 42 --wait --timeout 5m      # With timeout
21bkt pr checks 42 --fail-fast              # Exit on first failure
22
23# Checkout locally
24bkt pr checkout 42                        # Fetches to pr/42 branch

Branch Management

bash
1bkt branch list
2bkt branch list --filter "feature/*"
3bkt branch create release/1.9 --from main
4bkt branch delete feature/old-stuff
5bkt branch set-default main               # DC only
6bkt branch protect add main --type fast-forward-only  # DC only

Issue Tracking (Bitbucket Cloud Only)

bash
1bkt issue list --state open --kind bug
2bkt issue view 42 --comments
3bkt issue create -t "Login broken" -k bug -p major
4bkt issue edit 42 --assignee "{uuid}" --priority critical
5bkt issue close 42
6bkt issue reopen 42
7bkt issue comment 42 -b "Fixed in v1.2.0"
8bkt issue status                          # Your assigned/created issues

Issue kinds: bug, enhancement, proposal, task Priorities: trivial, minor, major, critical, blocker

Webhooks

bash
1bkt webhook list
2bkt webhook create --name "CI" --url https://ci.example.com/hook --event repo:refs_changed
3bkt webhook delete <id>
4bkt webhook test <id>

Pipelines (Cloud)

bash
1bkt pipeline run --ref main --var ENV=staging
2bkt pipeline list                         # Recent runs
3bkt pipeline view <uuid>                  # Pipeline details
4bkt pipeline logs <uuid>                  # Fetch logs
5bkt status pipeline <uuid>                # Alt: status check

Permissions (DC)

bash
1bkt perms project list --project DATA
2bkt perms project grant --project DATA --user alice --perm PROJECT_WRITE
3bkt perms repo list --project DATA --repo platform-api
4bkt perms repo grant --project DATA --repo api --user alice --perm REPO_WRITE

Raw API Access

For endpoints not yet wrapped:

bash
1bkt api /rest/api/1.0/projects --param limit=100 --json
2bkt api /repositories --param workspace=myteam --field pagelen=50

Output Modes

All commands support structured output:

bash
1bkt pr list --json                        # JSON output
2bkt pr list --yaml                        # YAML output
3bkt pr list --json | jq '.pull_requests[0].title'

Global Options

• --json / --yaml — Structured output
• --context <name> — Use specific context
• --project <key> — Override project (DC)
• --workspace <name> — Override workspace (Cloud)
• --repo <slug> — Override repository

Environment Variables

• BKT_CONFIG_DIR — Config directory override
• BKT_ALLOW_INSECURE_STORE — Allow file-based credential storage
• BKT_KEYRING_TIMEOUT — Keyring operation timeout (for example 2m)

References

• Full command reference: See references/commands.md