bkt

bkt – Bitbucket CLI

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.

This project (github.com/avivsinai/bitbucket-cli, binary bkt) is unrelated to the Rust bkt subprocess-caching tool and to the Bitbucket Enterprise CLI and other same-named bitbucket-cli packages.

brew install avivsinai/tap/bitbucket-cli
bkt --help

Recorded from a real bkt --help run — no Bitbucket login or token required. Other installers: WinGet, Scoop, Nix, Go, binaries.

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

WinGet (Windows)

winget install AvivSinai.Bitbucket-CLI

Scoop (Windows)

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

Go Install

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

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

Nix (NixOS / nix-darwin / Linux / macOS)

Run the latest master without installing:

nix run github:avivsinai/bitbucket-cli -- --version

Install into your user profile:

nix profile install github:avivsinai/bitbucket-cli

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.

Variable	Description
BKT_TOKEN	Authentication token. Bypasses keyring storage entirely.
BKT_HOST	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. Required for Cloud basic auth; not required for bearer auth.
BKT_AUTH_METHOD	Authentication method: basic or bearer. DC defaults to bearer when BKT_USERNAME is absent; Cloud defaults to basic. Use bearer for Cloud repository, project, or workspace access tokens.
BKT_PROJECT	Default Data Center project key (headless mode).
BKT_WORKSPACE	Default Bitbucket Cloud workspace (headless mode).
BKT_REPO	Default repository slug (headless mode).
BKT_CONFIG_DIR	Override the config file directory (default: $XDG_CONFIG_HOME/bkt).
BKT_HTTP_DEBUG	Set to 1 to log HTTP request URLs and response status codes.
BKT_ALLOW_INSECURE_STORE	Set to 1 to use encrypted file fallback when no OS keychain is available.

Minimal headless example (Data Center):

export BKT_HOST=https://bitbucket.example.com
export BKT_TOKEN=my-personal-access-token
export BKT_PROJECT=MYPROJ
export BKT_REPO=my-service

bkt pr list
bkt pr create --title "Automated PR" --source feature/my-branch

Minimal headless example (Bitbucket Cloud):

# User API token — basic auth
export BKT_HOST=https://bitbucket.org
export BKT_TOKEN=my-api-token
export BKT_USERNAME=me@example.com
export BKT_WORKSPACE=my-workspace
export BKT_REPO=my-repo

bkt pr list

# Repository, project, or workspace access token — bearer auth
export BKT_TOKEN=my-resource-access-token
export BKT_AUTH_METHOD=bearer
unset BKT_USERNAME

bkt pr list

Resource access tokens are not associated with a user. Commands that require authenticated-user identity, such as cross-repository bkt pr list --mine, still require user API-token or OAuth credentials.

From Source

git clone https://github.com/avivsinai/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:

Using Vercel's skills CLI:

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

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

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.

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

git clone https://github.com/avivsinai/bitbucket-cli.git
cp -r bitbucket-cli/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 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 <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

# 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 <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 (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)
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).

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:

bkt auth login https://bitbucket.org --kind cloud --username <bitbucket-username> --token <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.

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