bkt

SKILL.md

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:

# 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 '.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