Bitbucket CLI (bkt) is a command-line interface designed to streamline workflows on Bitbucket Cloud and Data Center. It enables developers to manage repositories, pull requests, and pipelines efficiently.
Key Features:
Efficient Workflow Management: Facilitates tasks such as creating pull requests and managing pipelines directly from the command line.
Seamless Integration: Supports integration with AI tools like Claude Code and Codex without requiring additional glue code, enhancing automation capabilities.
Authentication Options: Offers OAuth for Bitbucket Cloud and API tokens for Data Center, ensuring secure access to resources.
Environment Variables Configuration: Allows headless operation through environment variables, ideal for CI/CD pipelines.
Multi-platform Support: Installable via winget on Windows, making it accessible across different operating systems.
Audience & Benefit:
Ideal for developers working with Bitbucket, DevOps teams setting up CI/CD pipelines, and automation engineers seeking scalable solutions. By using bkt, these professionals can enhance their workflow efficiency, integrate seamlessly into existing processes, and scale operations effectively, driving productivity and innovation within their organizations.
README
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.
Pin to a specific tag or commit by appending a ref (e.g. github:avivsinai/bitbucket-cli/v1.2.3).
Don't have Nix yet? See nixos.asia/en/install for a quick setup guide (installs Nix with flakes enabled out of the box).
Binary Downloads
Download pre-built binaries for your platform from the releases page.
The .tar.gz and .zip release archives also include skills/bkt/, so the CLI and canonical skill files stay in sync when you install from a release artifact.
Official binaries support Bitbucket Cloud OAuth (bkt auth login --kind cloud --web) out of the box. Source and Nix builds can use the same flow by setting BKT_OAUTH_CLIENT_ID and BKT_OAUTH_CLIENT_SECRET in the environment. API-token login via --web-token works without that extra setup.
Bitbucket Pipelines
bkt supports fully config-free headless use via environment variables. Set BKT_TOKEN and BKT_HOST as secured repository variables — no prior bkt auth login or bkt context create step required.
pipelines:
default:
- step:
name: Open PR
script:
- export BKT_VERSION="0.26.0" # pin to a released version
- curl -sL "https://github.com/avivsinai/bitbucket-cli/releases/download/v${BKT_VERSION}/bkt_${BKT_VERSION}_linux_x86_64.tar.gz" | tar xz -C /tmp && install /tmp/bkt /usr/local/bin/
- bkt pr create --title "Auto PR" --source "$BITBUCKET_BRANCH"
Environment Variables
All bkt behaviour can be configured via environment variables, which is especially useful in containers and CI/CD pipelines.
Bitbucket server base URL (e.g. https://bitbucket.example.com). Required alongside BKT_TOKEN for config-free use. bitbucket.org is auto-detected as Cloud.
BKT_USERNAME
Username for basic authentication in headless mode.
BKT_AUTH_METHOD
Authentication method: basic or bearer. DC defaults to bearer when BKT_USERNAME is absent; Cloud always uses basic.
> Known Issue: Claude Code uses SSH to clone marketplace repos, which fails without SSH keys configured. See issue #14485. Use the skills or skild methods instead.
1. Authenticate against Bitbucket Data Center or Cloud
Bitbucket Data Center
# Guided flow: opens browser to create a Personal Access Token
bkt auth login https://bitbucket.mycorp.example --web-token
# Or provide credentials directly
bkt auth login https://bitbucket.mycorp.example --username alice --token
Create a Personal Access Token (PAT) in Bitbucket Data Center:
Go to Profile picture → Manage account → Personal access tokens
Click Create a token
Grant permissions: Repository Read, Repository Write, Project Read
Copy the token (you won't see it again)
Bitbucket Cloud
# Browser OAuth flow for Bitbucket Cloud
bkt auth login https://bitbucket.org --kind cloud --web
# Or provide credentials directly
bkt auth login https://bitbucket.org --kind cloud --username --token
Create an API token with scopes for Bitbucket Cloud:
Click Create and manage API tokens → Create API token with scopes
Name your token and set an expiry date
Select "Bitbucket" as the application (required!)
Grant scopes:
Account: Read (read:user:bitbucket) — Required for authentication
Repositories: Read, Write — For repo commands
Pull requests: Read, Write — For PR commands
Issues: Read, Write — For issue commands (optional)
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).
Legacy: App passwords (deprecated)
App passwords are deprecated. New app passwords cannot be created since September 2025, and existing ones will stop working June 2026. If you have an existing app password:
Note: For app passwords, use your Bitbucket username (not email).
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).
macOS note: Keychain prompts after brew upgrade
On macOS, every brew upgrade bkt may trigger one Keychain prompt because the
stored item's ACL is tied to the installed binary. Re-run bkt auth login once
after the upgrade to refresh the ACL, then subsequent invocations should not
prompt. Releases pin the Designated Requirement to the bundle identifier, so
the refresh is only needed once. Run bkt auth doctor to diagnose prompts
that persist beyond that; it never reads the stored secret.
> 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 create frontend-app --workspace myteam --cloud-project WEB
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}.
For repo create, --project, --forkable, --default-branch, and --scm are Data Center flags; --workspace and --cloud-project are Cloud flags. Host-specific create flags are rejected when they would otherwise be ignored.
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
bkt pr comments 42 --details # Review PR comments and thread IDs
bkt pr comments resolve 42 1001 # Resolve a top-level comment thread
bkt pr comments reopen 42 1001 # Reopen a resolved comment thread
bkt pr comments delete 42 1001 # Delete a PR comment
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.
For comment thread state changes, pass the top-level thread comment ID; replies
cannot be resolved or reopened directly.
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- 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
make check-skills # Verify generated skill mirrors
make sync-skills # Regenerate skill mirrors from skills/bkt
go test ./... runs fast smoke coverage that wires the CLI against an in-memory Bitbucket mock (see pkg/cmd/smoke/cli_smoke_test.go).
skills/bkt/ is canonical. After editing it, run make sync-skills to refresh
the committed .claude/skills/bkt/ and .agents/skills/bkt/ mirrors.
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.
