# bkt – Bitbucket CLI

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

[![CI](https://github.com/avivsinai/bitbucket-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/avivsinai/bitbucket-cli/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/avivsinai/bitbucket-cli/graph/badge.svg)](https://codecov.io/gh/avivsinai/bitbucket-cli) [![Release](https://img.shields.io/github/v/release/avivsinai/bitbucket-cli?cache=none)](https://github.com/avivsinai/bitbucket-cli/releases) [![Go Report Card](https://goreportcard.com/badge/github.com/avivsinai/bitbucket-cli?cache=none)](https://goreportcard.com/report/github.com/avivsinai/bitbucket-cli) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/avivsinai/bitbucket-cli/badge)](https://scorecard.dev/viewer/?uri=github.com/avivsinai/bitbucket-cli) [![Go Reference](https://pkg.go.dev/badge/github.com/avivsinai/bitbucket-cli.svg)](https://pkg.go.dev/github.com/avivsinai/bitbucket-cli) [![License](https://img.shields.io/github/license/avivsinai/bitbucket-cli?cache=none)](LICENSE) `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) ```bash brew install avivsinai/tap/bitbucket-cli ``` ### Scoop (Windows) ```powershell scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket scoop install bitbucket-cli ``` ### Go Install ```bash 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`. ### Binary Downloads Download pre-built binaries for your platform from the [releases page](https://github.com/avivsinai/bitbucket-cli/releases/latest). ### From Source ```bash 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:

Via skills (Recommended)

Using [Vercel's skills CLI](https://github.com/vercel-labs/add-skill): ```bash npx skills add avivsinai/bitbucket-cli -g -y ```

Via skild registry

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

Via Skills Marketplace

> **Known Issue**: Claude Code uses SSH to clone marketplace repos, which fails without SSH keys configured. See [issue #14485](https://github.com/anthropics/claude-code/issues/14485). Use the skills or skild methods instead. ```bash /plugin marketplace add avivsinai/skills-marketplace /plugin install bkt@avivsinai-marketplace ```

Manual install

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

## Getting started After installation, verify it works: ```bash bkt --help ``` ### 1. Authenticate against Bitbucket Data Center or Cloud #### Bitbucket Data Center ```bash # 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 ``` 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 ```bash # 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 --token ``` Create an **API token with scopes** for Bitbucket Cloud: 1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens) 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).

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: ```bash bkt auth login https://bitbucket.org --kind cloud --username --token ``` 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`). ### 2. Create and activate a context #### Bitbucket Data Center ```bash bkt context create dc-prod --host bitbucket.mycorp.example --project ABC --set-active bkt context list ``` #### Bitbucket Cloud ```bash 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 ```bash 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 ```bash 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) ```bash 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 ```bash 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: ```bash 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](https://github.com/gitleaks/gitleaks)), dependency updates ([Dependabot](https://github.com/dependabot)), and security posture tracking ([OSSF Scorecard](https://github.com/ossf/scorecard)). Found a security issue? See our [security policy](SECURITY.md) 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 ```bash 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: ```bash 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](https://github.com/avivsinai/bitbucket-cli/issues/new?template=feature_request.md) - **Bug Reports**: File an [issue](https://github.com/avivsinai/bitbucket-cli/issues/new?template=bug_report.md) ## License `bkt` is available under the [MIT License](LICENSE).

bkt

Installation

SKILL.md