bitbucket-cli

bkt – Bitbucket CLI

Bitbucket Cloud & Data Center workflows for developers, coding agents, and automation-first teams.

bkt is a stand-alone Bitbucket command-line interface that targets Bitbucket Data Center and Bitbucket Cloud. It mirrors the ergonomics of gh and delivers a consistent JSON/YAML contract for automation.

Built for AI & automation: Drop bkt into Claude Code, Codex and other coding agents, or shell scripts and they inherit structured output, predictable flags, and safe defaults—no glue code required.

Installation

Homebrew (macOS/Linux)

brew install avivsinai/tap/bitbucket-cli

Scoop (Windows)

scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket
scoop install bitbucket-cli

Go Install

go install github.com/alessandro308/bitbucket-cli/cmd/bkt@latest

This installs bkt to $GOPATH/bin (or $HOME/go/bin by default). Ensure the directory is in your $PATH.

Binary Downloads

Download pre-built binaries for your platform from the releases page.

From Source

git clone https://github.com/alessandro308/bitbucket-cli.git
cd bitbucket-cli
make build   # produces ./bin/bkt
./bin/bkt --help

Claude Code / Codex Skill

Install the bkt skill to give Claude Code or Codex CLI native Bitbucket knowledge:

npx skills add avivsinai/bitbucket-cli -g -y

npx skild install @avivsinai/bkt -t claude -y

/plugin marketplace add avivsinai/skills-marketplace
/plugin install bkt@avivsinai-marketplace

git clone https://github.com/alessandro308/bitbucket-cli.git
cp -r bitbucket-cli/.claude/skills/bkt ~/.claude/skills/

Getting started

After installation, verify it works:

bkt --help

1. Authenticate against Bitbucket Data Center or Cloud

Bitbucket Data Center

# Guided flow: opens browser to create token
bkt auth login https://bitbucket.mycorp.example --web

# Or provide credentials directly
bkt auth login https://bitbucket.mycorp.example --username alice --token <PAT>

Create a Personal Access Token (PAT) in Bitbucket Data Center:

1. Go to Profile picture → Manage account → Personal access tokens
2. Click Create a token
3. Grant permissions: Repository Read, Repository Write, Project Read
4. Copy the token (you won't see it again)

Bitbucket Cloud

# Guided flow: opens browser to create token
bkt auth login https://bitbucket.org --kind cloud --web

# Or provide credentials directly
bkt auth login https://bitbucket.org --kind cloud --username <email> --token <api-token>

Create an API token with scopes for Bitbucket Cloud:

1. Go to Atlassian Account Settings
2. Click Create and manage API tokens → Create API token with scopes
3. Name your token and set an expiry date
4. Select "Bitbucket" as the application (required!)
5. Grant scopes:
   • Account: Read — Required for authentication
   • Repositories: Read, Write — For repo commands
   • Pull requests: Read, Write — For PR commands
   • Issues: Read, Write — For issue commands (optional)
6. Click Create and copy the token immediately

Warning: General Atlassian API tokens won't work. You must select "Bitbucket" as the application when creating the token.

Note: Use your Atlassian account email as the username (not your Bitbucket username).

bkt auth login https://bitbucket.org --kind cloud --username <bitbucket-username> --token <app-password>

Credential storage

Access tokens are stored in your OS keychain (Keychain Access on macOS, Windows Credential Manager, or Secret Service/KWallet on Linux) while host metadata lives in $XDG_CONFIG_HOME/bkt/config.yml. Pass --allow-insecure-store (or set BKT_ALLOW_INSECURE_STORE=1) to permit the encrypted file backend on systems without a native keychain.

If your keyring requires an interactive unlock prompt, you can increase the keyring timeout via BKT_KEYRING_TIMEOUT (for example BKT_KEYRING_TIMEOUT=2m).

2. Create and activate a context

Bitbucket Data Center

bkt context create dc-prod --host bitbucket.mycorp.example --project ABC --set-active
bkt context list

Bitbucket Cloud

bkt context create cloud-prod --host api.bitbucket.org --workspace myteam --set-active
bkt context list

Tip: Run bkt auth status to see configured hosts and the exact host value to use with --host.

Contexts capture the host mapping, default project/workspace, and optional default repository for commands.

3. Work with repositories

bkt repo list --limit 20
bkt repo list --workspace myteam --limit 10   # Cloud workspace override
bkt repo view platform-api
bkt repo create data-pipeline --description "Data ingestion" --project DATA
bkt repo browse --project DATA --repo platform-api
bkt repo clone platform-api --project DATA --ssh

repo list/repo view automatically target the right REST API for your active context: Data Center uses /rest/api/1.0/projects/{projectKey}/repos, while Cloud uses /2.0/repositories/{workspace}.

4. Pull request workflows

bkt pr list --state OPEN --limit 10
bkt pr create --title "feat: cache" --source feature/cache --target main --reviewer alice
bkt pr merge 42 --message "merge: feature/cache"
bkt pr checks 42                              # Show build/CI status
bkt pr checks 42 --wait                       # Wait for builds to complete
bkt pr checks 42 --wait --timeout 5m          # Wait with timeout
bkt pr checks 42 --wait --max-interval 1m     # Custom backoff cap

The CLI wraps Bitbucket pull-request endpoints for creation, listing, review, and merge operations. The checks command displays build status with color-coded output (green for success, red for failure, yellow for in-progress) and supports polling until all builds complete. Polling uses exponential backoff with jitter to avoid overwhelming the API during long builds.

5. Issue tracking (Bitbucket Cloud only)

bkt issue list --state open --kind bug           # List open bugs
bkt issue view 42 --comments                     # View issue with comments
bkt issue create -t "Login broken" -k bug -p major
bkt issue edit 42 --assignee "{abc-123}" --priority critical
bkt issue close 42                               # Close an issue
bkt issue reopen 42                              # Reopen a closed issue
bkt issue comment 42 -b "Fixed in v1.2.0"        # Add a comment
bkt issue status                                 # Show your assigned/created issues

# Attachments
bkt issue attachment list 42                     # List attachments
bkt issue attachment upload 42 screenshot.png    # Upload file(s)
bkt issue attachment download 42 --all           # Download all attachments
bkt issue attachment delete 42 old-file.txt      # Delete an attachment

Note: The issue tracker is only available for Bitbucket Cloud. Bitbucket Data Center uses Jira for issue tracking.

6. Branch, permission, webhook, pipeline, and extension management

bkt branch list --workspace myteam           # Cloud branch listing
bkt branch create release/1.9 --from main    # Data Center branch utils
bkt perms repo list --project DATA --repo platform-api
bkt webhook create --name "CI" --url https://ci.example.com/hook --event repo:refs_changed
bkt pipeline run --workspace myteam --repo api --ref main --var ENV=staging
bkt extension install https://github.com/example/bkt-hello.git
bkt extension exec hello -- --flag=1
bkt status pipeline {pipeline-uuid}
bkt status rate-limit

Branch utilities use Bitbucket's Branch Utils REST API for listing, creation, deletion, and default updates. Permission and webhook commands map to their respective REST endpoints for consistent automation.

Extensions are cloned into $XDG_CONFIG_HOME/bkt/extensions (or the directory configured via BKT_CONFIG_DIR) and executed in-place. Binaries should follow the bkt-<name> naming convention so the CLI can discover them automatically.

Structured output & raw API access

Every command supports the global --json and --yaml flags for automation-ready output.

For endpoints that are not yet wrapped, reach directly for the API escape hatch:

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

Security

This project uses automated secret scanning (gitleaks), dependency updates (Dependabot), and security posture tracking (OSSF Scorecard).

Found a security issue? See our security policy for responsible disclosure.

Development

Project Layout

cmd/bkt/             # CLI entry point
internal/bktcmd/     # Main() wiring (factory + root command)
internal/build/      # Version metadata (overridden via ldflags)
internal/config/     # Context and host configuration
internal/remote/     # Git remote parsing utilities
pkg/cmd/             # Cobra command implementations (auth, repo, pr, ...)
pkg/cmdutil/         # Shared command helpers and factory wiring
pkg/iostreams/       # IO stream abstractions
pkg/bbdc/            # Bitbucket Data Center client implementation
pkg/bbcloud/         # Bitbucket Cloud client implementation
pkg/format/          # Output rendering helpers
pkg/httpx/           # Shared HTTP client and retry logic

Building & Testing

make build      # Build the binary to ./bin/bkt
make test       # Run unit tests
make fmt        # Format code
make lint       # Run linters
make tidy       # Tidy go modules

go test ./... runs fast smoke coverage that wires the CLI against an in-memory Bitbucket mock (see pkg/cmd/smoke/cli_smoke_test.go).

Troubleshooting

Debug HTTP Requests

To see API request URLs and response status codes, set the BKT_HTTP_DEBUG environment variable:

BKT_HTTP_DEBUG=1 bkt pipeline view 10

This outputs request method/URL and response status, useful for diagnosing API errors.

Support

• Questions / Ideas: File an issue
• Bug Reports: File an issue

License

bkt is available under the MIT License.