bkt — Claude Code plugin: Bitbucket CLI for agents
The bkt plugin for Claude Code and Codex gives agents access to Bitbucket Cloud and Data Center repositories and pull requests, with machine-readable command output.
MIT ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install bkt@awesome-codex-pluginsWhat bkt does
The plugin puts the bkt binary and a matching skill into your project. One tool covers Bitbucket Cloud and Bitbucket Data Center, and its commands follow the shape of gh. Output is JSON or YAML under a stable contract, which makes piping it into scripts painless. An MCP server comes along too, so the agent can reach Bitbucket through that route.
Inside a clone, the tool picks up the workspace (or project) and repository name from the git remote, provided that remote points at the host of the active context. Cloud sign-in opens a browser and uses OAuth. Data Center takes a personal access token instead. Tokens sit in the operating system keychain.
Containers and minimal Linux images often have no keychain at all, so the login is not kept until you pass --allow-insecure-store or set BKT_ALLOW_INSECURE_STORE=1, sending the token to an encrypted file. Building from source needs Go 1.26+.
What it helps with
- list your own pull requests without leaving the terminal
- open a pull request from a feature branch into main
- dump project issues as JSON for a script
- trigger a pipeline and inspect webhooks
- handle Cloud and Data Center with one binary
Example prompts for the agent
- Show my pull requests in Bitbucket with
bkt pr list --mine. - Open a pull request from
feature/cacheintomainusingbkt pr create. - List my hosts and token expiry with
bkt auth status.
How to install bkt
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install bkt@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about bkt
How do I install bkt in Claude Code?
Add the marketplace first: /plugin marketplace add hashgraph-online/awesome-codex-plugins. Then run /plugin install bkt@awesome-codex-plugins.
What does bkt do?
It is a command line client for Bitbucket Cloud and Data Center: repositories, pull requests, branches, issues, webhooks and pipelines. The package also includes an agent skill and an MCP server.
Can I use it on a machine without a keychain?
Yes. Pass --allow-insecure-store when logging in, or set BKT_ALLOW_INSECURE_STORE=1. The token then goes to an encrypted file rather than the system keychain.
Source text
bitbucket-cli · MIT
# bkt – Bitbucket CLI <p align="center"><em>Bitbucket Cloud & Data Center workflows for developers, coding agents, and automation-first teams.</em></p> [](https://github.com/avivsinai/bitbucket-cli/actions/workflows/ci.yml) [](https://codecov.io/gh/avivsinai/bitbucket-cli) [](https://github.com/avivsinai/bitbucket-cli/releases) [](https://formulae.brew.sh/formula/bitbucket-cli) [](https://scorecard.dev/viewer/?uri=github.com/avivsinai/bitbucket-cli) [](https://pkg.go.dev/github.com/avivsinai/bitbucket-cli) [](LICENSE) `bkt` is one command-line interface for Bitbucket Cloud **and** Bitbucket Data Center. It follows the ergonomics of `gh`, gives every command a stable JSON/YAML output contract, and ships an agent skill and an MCP server so coding agents can work with Bitbucket too. This project (`github.com/avivsinai/bitbucket-cli`, binary `bkt`) is unrelated to the Rust [`bkt`](https://github.com/dimo414/bkt) subprocess-caching tool, the [Bitbucket Enterprise CLI](https://github.com/swisscom/bitbucket-cli), and other packages named `bitbucket-cli`. <p align="center"> <img src="docs/demo.gif" alt="Recorded terminal: brew install avivsinai/tap/bitbucket-cli, then bkt --help" width="860"> </p> ## Quick start ```bash brew install bitbucket-cli # Bitbucket Cloud: log in through your browser bkt auth login https://bitbucket.org --kind cloud --web bkt context create cloud --host api.bitbucket.org --workspace myteam --set-active # Bitbucket Data Center: paste a Personal Access Token bkt auth login https://bitbucket.example.com --web-token bkt context create dc --host bitbucket.example.com --project ABC --set-active bkt pr list --mine bkt pr create --title "feat: cache" --source feature/cache --target main ``` Inside a clone, `bkt` takes the workspace or project and the repository from the git remote when the remote points at the active context's host. ## Install | Platform | Command | |---|---| | macOS / Linux ([Homebrew core](https://formulae.brew.sh/formula/bitbucket-cli)) | `brew install bitbucket-cli` | | Windows ([WinGet](https://github.com/microsoft/winget-pkgs)) | `winget install AvivSinai.Bitbucket-CLI` | | Windows ([Scoop](https://github.com/avivsinai/scoop-bucket)) | `scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket`<br>`scoop install bitbucket-cli` | | Go 1.26+ | `go install github.com/avivsinai/bitbucket-cli/cmd/bkt@latest` | | Nix (flakes) | `nix profile install github:avivsinai/bitbucket-cli` | | Debian / Ubuntu | `.deb` from the [latest release](https://github.com/avivsinai/bitbucket-cli/releases/latest) | | Any | Archive from the [latest release](https://github.com/avivsinai/bitbucket-cli/releases/latest) | Every install method supports Bitbucket Cloud browser login with no extra setup. - **Homebrew tap.** `brew install avivsinai/tap/bitbucket-cli` installs the prebuilt release binary, signed with a Developer ID and notarized, instead of Homebrew's source build. Both provide the same `bkt` command, so install only one. - **Nix.** `nix run github:avivsinai/bitbucket-cli -- --version` runs `master` without installing. Append a ref, such as `github:avivsinai/bitbucket-cli/v0.36.0`, to pin a release. - **Release archives** also contain `skills/bkt/`, so the CLI and its agent skill stay on one version. - **Verify a download.** Each release publishes `checksums.txt`, a CycloneDX SBOM, and GitHub build provenance: `gh attestation verify <archive> --repo avivsinai/bitbucket-cli`. - **From source.** `git clone https://github.com/avivsinai/bitbucket-cli && cd bitbucket-cli && make build` produces `./bin/bkt`. ## Authenticate `bkt auth login` checks a credential against the host before it stores it. `bkt auth status` lists your hosts and when OAuth tokens expire. ### Bitbucket Cloud **Browser OAuth (recommended).** `bkt` opens Bitbucket in your browser. After you approve access, `bkt` stores a short-lived access token and refreshes it automatically: ```bash bkt auth login https://bitbucket.org --kind cloud --web ``` To use your own OAuth consumer instead of bkt's, set both `BKT_OAUTH_CLIENT_ID` and `BKT_OAUTH_CLIENT_SECRET` before you log in. **API token.** `--web-token` opens Atlassian's token page, then prompts for the token: ```bash bkt auth login https://bitbucket.org --kind cloud --web-token # or non-interactively bkt auth login https://bitbucket.org --kind cloud --username <atlassian-email> --with-token < token.txt ``` Create the token under [Atlassian account → Security → API tokens](https://id.atlassian.com/manage-profile/security/api-tokens) with **Create API token with scopes**. Choose **Bitbucket** as the app (general Atlassian tokens do not work) and grant: - **Account: Read** (`read:user:bitbucket`), required - **Repositories: Read, Write**, plus **Admin** for `bkt repo create` - **Pull requests: Read, Write** - **Pipelines** and **Webhooks**, if you use `bkt pipeline`, `bkt variable`, or `bkt webhook` Log in with your Atlassian account **email**, not your Bitbucket username. Atlassian has removed app passwords; replace any you still use with an API token. ### Bitbucket Data Center ```bash bkt auth login https://bitbucket.example.com --web-token # or non-interactively bkt auth login https://bitbucket.example.com --username alice --with-token < pat.txt ``` Create the Personal Access Token under **Profile picture → Manage account → Personal access tokens** with **Repository Read/Write** and **Project Read**. ### Credential storage Tokens live in the OS keychain: macOS Keychain, Windows Credential Manager, or Secret Service/KWallet on Linux. Host metadata lives in `$XDG_CONFIG_HOME/bkt/config.yml` and never contains a token. - **No keychain** (containers, minimal Linux): pass `--allow-insecure-store` or set `BKT_ALLOW_INSECURE_STORE=1` to use an encrypted file instead. - **Slow unlock prompts:** raise `BKT_KEYRING_TIMEOUT`, for example `BKT_KEYRING_TIMEOUT=2m`. - **A passphrase prompt on every run (Linux):** some Secret Service providers, such as KWallet, create a separate wallet for bkt's `bkt` collection. Set `BKT_KEYRING_COLLECTION` to your provider's default collection (for example `kdewallet`) to share the wallet you already unlocked. Add credentials stored under the old collection again. Distributors can set the default at build time with `-ldflags -X github.com/avivsinai/bitbucket-cli/internal/secret.defaultKeyringCollection=<collection>`; the environment variable still wins. - **macOS Keychain prompts:** release binaries are signed with one Developer ID, so after you choose **Always Allow** once, upgrades keep access. `bkt auth doctor` explains prompts that persist; it never reads the stored secret. ### CI and containers Set `BKT_TOKEN` and `BKT_HOST`, and `bkt` needs no login and no config file: ```bash # Data Center export BKT_HOST=https://bitbucket.example.com BKT_TOKEN=<pat> BKT_PROJECT=MYPROJ BKT_REPO=my-service # Cloud, user API token (basic auth) export BKT_HOST=https://bitbucket.org BKT_TOKEN=<api-token> [email protected] \ BKT_WORKSPACE=my-workspace BKT_REPO=my-repo # Cloud, repository / project / workspace access token (bearer auth) export BKT_HOST=https://bitbucket.org BKT_TOKEN=<access-token> BKT_AUTH_METHOD=bearer bkt pr list ``` Resource access tokens belong to no user. Commands that need a user identity, such as `bkt pr list --mine` across repositories, still need a user API token or OAuth. In Bitbucket Pipelines, store `BKT_TOKEN` and `BKT_HOST` as secured [repository variables](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/) and install a pinned release: ```yaml pipelines: default: - step: name: Open PR script: - export BKT_VERSION=0.36.0 # pin the release you have tested - curl -fsSL "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" ``` | Variable | Purpose | |---|---| | `BKT_TOKEN` | Token for every request; bypasses the keychain. | | `BKT_HOST` | Base URL, for example `https://bitbucket.example.com`. `bitbucket.org` selects Cloud. | | `BKT_USERNAME` | Username for basic auth. Required for Cloud user API tokens. | | `BKT_AUTH_METHOD` | `basic` or `bearer`. Data Center defaults to `bearer` without `BKT_USERNAME`; Cloud defaults to `basic`. | | `BKT_PROJECT` / `BKT_WORKSPACE` / `BKT_REPO` | Default Data Center project, Cloud workspace, and repository. | | `BKT_CONFIG_DIR` | Config directory (default `$XDG_CONFIG_HOME/bkt`). | | `BKT_OAUTH_CLIENT_ID` / `BKT_OAUTH_CLIENT_SECRET` | Your own Bitbucket Cloud OAuth consumer for `--web`; set both. | | `BKT_ALLOW_INSECURE_STORE` | `1` allows the encrypted file store when no keychain exists. | | `BKT_KEYRING_TIMEOUT` | Keychain operation timeout, for example `2m`. | | `BKT_KEYRING_COLLECTION` | Secret Service collection (Linux). | | `BKT_HTTP_DEBUG` | `1` logs each request URL and response status. | ## Use it A context binds a host to a default workspace or project, and optionally a repository. `bkt auth status` prints the host value to pass to `--host`. ```bash bkt context create cloud --host api.bitbucket.org --workspace myteam --set-active bkt context list ``` **Repositories** ```bash bkt repo list --limit 20 bkt repo view platform-api bkt repo create data-pipeline --description "Data ingestion" --project DATA # Data Center bkt repo create frontend-app --workspace myteam --cloud-project WEB # Cloud bkt repo clone platform-api --project DATA --ssh bkt repo browse --project DATA --repo platform-api bkt repo downloads upload before.png after.png # Cloud: host images for PR descriptions ``` **Pull requests** ```bash bkt pr list --state OPEN --limit 10 bkt pr create --title "feat: cache" --source feature/cache --target main --reviewer alice bkt pr checks 42 --wait --timeout 5m # wait for builds, with backoff bkt pr comments 42 --details # threads with file/line anchors bkt pr comments resolve 42 1001 bkt pr merge 42 --message "merge: feature/cache" ``` **Issues.** Atlassian removed Bitbucket Cloud Issues in August 2026, and Data Center never had them; track issues in Jira. **Pipelines, branches, permissions, webhooks** ```bash bkt pipeline run --workspace myteam --repo api --ref main --var ENV=staging bkt pipeline run --ref master --selector-type custom --selector-pattern deploy-to-production bkt status pipeline {pipeline-uuid} bkt branch create release/1.9 --from main 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 status rate-limit ``` **Anything else.** `bkt api` calls any REST endpoint with your stored credentials: ```bash bkt api /rest/api/1.0/projects --param limit=100 --json # Data Center bkt api /repositories --param workspace=myteam --field pagelen=50 # Cloud ``` **Output for scripts.** Commands accept `--json`, `--yaml`, `--jq <expr>`, and `--template <go-template>`. **Extensions.** `bkt extension install <git-url>` adds a `bkt-<name>` command; `bkt extension exec <name>` runs it. **Shell completion.** `bkt completion bash|zsh|fish|powershell`. The Homebrew core formula installs completions for you. The full command reference, generated from `bkt --help`, is in [`skills/bkt/rules/`](skills/bkt/rules/). ## Coding agents **Agent skill.** The `bkt` skill teaches Claude Code, Codex, and other agents to use `bkt`: ```bash npx skills add avivsinai/bitbucket-cli -g -y ``` Alternatives: `npx skild install @avivsinai/bkt -t claude -y`; the Claude Code marketplace (`/plugin marketplace add avivsinai/skills-marketplace`, then `/plugin install bkt@avivsinai-marketplace`); or copy [`skills/bkt`](skills/bkt) into `~/.claude/skills/`. **MCP server.** `bkt mcp serve` exposes read-only Bitbucket tools over MCP stdio for one pinned context: ```bash claude mcp add bitbucket -- bkt mcp serve ``` **Skills hosted on Bitbucket.** `bkt skill` installs [Agent Skills](https://agentskills.io/specification) from Bitbucket repositories, mirroring [`gh skill`](https://github.com/cli/cli#agent-skills): ```bash bkt skill install myteam/agent-skills # list what a repository publishes bkt skill install myteam/agent-skills [email protected] --agent claude-code --scope user bkt skill list bkt skill update --all bkt skill publish --tag v1.2.0 # validate and tag your own skills ``` `--agent` selects the target agent (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and more; see `bkt skill install --help`). The default, `universal`, writes to the shared `.agents/skills` directory. Installed skills record their source in `SKILL.md` frontmatter, and `bkt skill update` compares it with the repository; `@version` or `--pin` pins a skill until `--unpin`. `bkt skill search` uses the Bitbucket Cloud code-search API, which Atlassian has [announced for deprecation](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-other-operations/#api-workspaces-workspace-search-code-get); Data Center has no equivalent API. ## Troubleshooting - `BKT_HTTP_DEBUG=1 bkt <command>` prints each request URL and response status. - `bkt auth status` shows each host, its auth method, and OAuth expiry. - `bkt auth doctor` diagnoses keychain prompts and timeouts. ## Project - [Contributing](CONTRIBUTING.md): build, test, and pull request workflow - [Security policy](SECURITY.md) and [security operations](docs/SECURITY.md) - [Changelog](CHANGELOG.md) · [Versioning](docs/VERSIONING.md) · [Privacy](docs/PRIVACY.md) - Questions and bugs: [GitHub issues](https://github.com/avivsinai/bitbucket-cli/issues) `bkt` is available under the [MIT License](LICENSE).
© Aviv Sinai · MIT · hashgraph-online/awesome-codex-plugins