Skip to main content
plugin CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install bkt@awesome-codex-plugins
Open on GitHub

What 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/cache into main using bkt 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-plugins

Step 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>

[![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)
[![Homebrew](https://img.shields.io/homebrew/v/bitbucket-cli)](https://formulae.brew.sh/formula/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 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

Similar plugins

All plugins for Git and GitHub →

From the same set391

The whole set →
calle Connects the CALL-E CLI to plan, execute, and monitor automated phone calls directly from your AI coding environment. CX Codex ★ 1,596repo stars burpsuite-mcp-bridge burpsuite-mcp-bridge is a Claude Code plugin that connects Burp Suite workflows over MCP to search traffic, replay requests with bounded changes, and export evidence. CX Codex ★ 1,596repo stars bulktranscripts bulktranscripts — a hosted MCP server that pulls YouTube captions for a single video, a whole channel or a playlist and hands them to your agent as text. It also searches YouTube and watches for new uploads. CX Codex ★ 1,596repo stars build-remote-agent build-remote-agent pairs local coding sessions with a phone via the gbr-agent binary. Lets you watch terminal output and send input without opening incoming firewall ports. CX Codex ★ 1,596repo stars bankbridge Wires the BankBridge remote MCP server into Claude so the agent can read your US bank, card and brokerage accounts and answer spending questions from live data. CX Codex ★ 1,596repo stars babeldoc-pdf-translate babeldoc-pdf-translate translates PDF files while preserving the original visual layout using a local BabelDOC engine, custom glossaries, and bilingual output. CX Codex ★ 1,596repo stars axonflow axonflow is a Claude Code plugin that checks Codex actions against policies, detects PII and secrets, and records audit events. Blocked calls get a decision_id. CX Codex ★ 1,596repo stars autocad-tianzheng-tools autocad-tianzheng-tools wires Claude to AutoCAD and Tianzheng HVAC through a local MCP server, so the agent can open DWG drawings and carry out drawing operations. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open