Skip to content
Back to search

bkt

Bitbucket CLI - manage repos, PRs, branches, webhooks, and pipelines for both Data Center and Cloud

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/avivsinai--bitbucket-cli/badge.svg)](/listings/avivsinai--bitbucket-cli)

HTML

<a href="/listings/avivsinai--bitbucket-cli"><img src="/api/listings/avivsinai--bitbucket-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 24 lines
  1. {
  2. "name": "bkt",
  3. "version": "0.40.2",
  4. "description": "Bitbucket CLI - manage repos, PRs, branches, webhooks, and pipelines for both Data Center and Cloud",
  5. "author": {
  6. "name": "Aviv Sinai",
  7. "url": "https://github.com/avivsinai"
  8. },
  9. "repository": "https://github.com/avivsinai/bitbucket-cli",
  10. "license": "MIT",
  11. "skills": "./skills/",
  12. "keywords": [
  13. "bitbucket",
  14. "git",
  15. "pr",
  16. "pull-request",
  17. "ci",
  18. "pipeline",
  19. "devops",
  20. "cli",
  21. "datacenter",
  22. "cloud"
  23. ]
  24. }
README.md · README · 268 lines
  1. # bkt – Bitbucket CLI
  2. <p align="center"><em>Bitbucket Cloud & Data Center workflows for developers, coding agents, and automation-first teams.</em></p>
  3. [![CI](https://github.com/avivsinai/bitbucket-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/avivsinai/bitbucket-cli/actions/workflows/ci.yml)
  4. [![codecov](https://codecov.io/gh/avivsinai/bitbucket-cli/graph/badge.svg)](https://codecov.io/gh/avivsinai/bitbucket-cli)
  5. [![Release](https://img.shields.io/github/v/release/avivsinai/bitbucket-cli?cache=none)](https://github.com/avivsinai/bitbucket-cli/releases)
  6. [![Homebrew](https://img.shields.io/homebrew/v/bitbucket-cli)](https://formulae.brew.sh/formula/bitbucket-cli)
  7. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/avivsinai/bitbucket-cli/badge)](https://scorecard.dev/viewer/?uri=github.com/avivsinai/bitbucket-cli)
  8. [![Go Reference](https://pkg.go.dev/badge/github.com/avivsinai/bitbucket-cli.svg)](https://pkg.go.dev/github.com/avivsinai/bitbucket-cli)
  9. [![License](https://img.shields.io/github/license/avivsinai/bitbucket-cli?cache=none)](LICENSE)
  10. `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.
  11. 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`.
  12. <p align="center">
  13. <img src="docs/demo.gif" alt="Recorded terminal: brew install avivsinai/tap/bitbucket-cli, then bkt --help" width="860">
  14. </p>
  15. ## Quick start
  16. ```bash
  17. brew install bitbucket-cli
  18. # Bitbucket Cloud: log in through your browser
  19. bkt auth login https://bitbucket.org --kind cloud --web
  20. bkt context create cloud --host api.bitbucket.org --workspace myteam --set-active
  21. # Bitbucket Data Center: paste a Personal Access Token
  22. bkt auth login https://bitbucket.example.com --web-token
  23. bkt context create dc --host bitbucket.example.com --project ABC --set-active
  24. bkt pr list --mine
  25. bkt pr create --title "feat: cache" --source feature/cache --target main
  26. ```
  27. 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.
  28. ## Install
  29. | Platform | Command |
  30. |---|---|
  31. | macOS / Linux ([Homebrew core](https://formulae.brew.sh/formula/bitbucket-cli)) | `brew install bitbucket-cli` |
  32. | Windows ([WinGet](https://github.com/microsoft/winget-pkgs)) | `winget install AvivSinai.Bitbucket-CLI` |
  33. | Windows ([Scoop](https://github.com/avivsinai/scoop-bucket)) | `scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket`<br>`scoop install bitbucket-cli` |
  34. | Go 1.26+ | `go install github.com/avivsinai/bitbucket-cli/cmd/bkt@latest` |
  35. | Nix (flakes) | `nix profile install github:avivsinai/bitbucket-cli` |
  36. | Debian / Ubuntu | `.deb` from the [latest release](https://github.com/avivsinai/bitbucket-cli/releases/latest) |
  37. | Any | Archive from the [latest release](https://github.com/avivsinai/bitbucket-cli/releases/latest) |
  38. Every install method supports Bitbucket Cloud browser login with no extra setup.
  39. - **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.
  40. - **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.
  41. - **Release archives** also contain `skills/bkt/`, so the CLI and its agent skill stay on one version.
  42. - **Verify a download.** Each release publishes `checksums.txt`, a CycloneDX SBOM, and GitHub build provenance: `gh attestation verify <archive> --repo avivsinai/bitbucket-cli`.
  43. - **From source.** `git clone https://github.com/avivsinai/bitbucket-cli && cd bitbucket-cli && make build` produces `./bin/bkt`.
  44. ## Authenticate
  45. `bkt auth login` checks a credential against the host before it stores it. `bkt auth status` lists your hosts and when OAuth tokens expire.
  46. ### Bitbucket Cloud
  47. **Browser OAuth (recommended).** `bkt` opens Bitbucket in your browser. After you approve access, `bkt` stores a short-lived access token and refreshes it automatically:
  48. ```bash
  49. bkt auth login https://bitbucket.org --kind cloud --web
  50. ```
  51. 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.
  52. **API token.** `--web-token` opens Atlassian's token page, then prompts for the token:
  53. ```bash
  54. bkt auth login https://bitbucket.org --kind cloud --web-token
  55. # or non-interactively
  56. bkt auth login https://bitbucket.org --kind cloud --username <atlassian-email> --with-token < token.txt
  57. ```
  58. 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:
  59. - **Account: Read** (`read:user:bitbucket`), required
  60. - **Repositories: Read, Write**, plus **Admin** for `bkt repo create`
  61. - **Pull requests: Read, Write**
  62. - **Pipelines** and **Webhooks**, if you use `bkt pipeline`, `bkt variable`, or `bkt webhook`
  63. 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.
  64. ### Bitbucket Data Center
  65. ```bash
  66. bkt auth login https://bitbucket.example.com --web-token
  67. # or non-interactively
  68. bkt auth login https://bitbucket.example.com --username alice --with-token < pat.txt
  69. ```
  70. Create the Personal Access Token under **Profile picture → Manage account → Personal access tokens** with **Repository Read/Write** and **Project Read**.
  71. ### Credential storage
  72. Tokens live in the OS keychain: macOS Keychain, Windows Credential Manager, or Secret Service/KWallet on Linux. Host metadata lives in `config.yml` in the bkt config directory (`~/Library/Application Support/bkt` on macOS, `%AppData%\bkt` on Windows, `$XDG_CONFIG_HOME/bkt` or `~/.config/bkt` on Linux) and never contains a token.
  73. - **No keychain** (containers, minimal Linux): pass `--allow-insecure-store` or set `BKT_ALLOW_INSECURE_STORE=1` to use an encrypted file instead.
  74. - **Slow unlock prompts:** raise `BKT_KEYRING_TIMEOUT`, for example `BKT_KEYRING_TIMEOUT=2m`.
  75. - **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.
  76. - **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.
  77. ### CI and containers
  78. Set `BKT_TOKEN` and `BKT_HOST`, and `bkt` needs no login and no config file:
  79. ```bash
  80. # Data Center
  81. export BKT_HOST=https://bitbucket.example.com BKT_TOKEN=<pat> BKT_PROJECT=MYPROJ BKT_REPO=my-service
  82. # Cloud, user API token (basic auth)
  83. export BKT_HOST=https://bitbucket.org BKT_TOKEN=<api-token> BKT_USERNAME=me@example.com \
  84. BKT_WORKSPACE=my-workspace BKT_REPO=my-repo
  85. # Cloud, repository / project / workspace access token (bearer auth)
  86. export BKT_HOST=https://bitbucket.org BKT_TOKEN=<access-token> BKT_AUTH_METHOD=bearer
  87. bkt pr list
  88. ```
  89. When `BKT_HOST` is set, `BKT_TOKEN` is used for that host only. The pair wins over an active context that points at another host, and `bkt` refuses to send the token to a different host named with `--context` or `--host`.
  90. 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.
  91. 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:
  92. ```yaml
  93. pipelines:
  94. default:
  95. - step:
  96. name: Open PR
  97. script:
  98. - export BKT_VERSION=0.36.0 # pin the release you have tested
  99. - 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/
  100. - bkt pr create --title "Auto PR" --source "$BITBUCKET_BRANCH"
  101. ```
  102. | Variable | Purpose |
  103. |---|---|
  104. | `BKT_TOKEN` | Token for every request; bypasses the keychain. |
  105. | `BKT_HOST` | Base URL, for example `https://bitbucket.example.com`. `bitbucket.org` selects Cloud. |
  106. | `BKT_USERNAME` | Username for basic auth. Required for Cloud user API tokens. |
  107. | `BKT_AUTH_METHOD` | `basic` or `bearer`. Data Center defaults to `bearer` without `BKT_USERNAME`; Cloud defaults to `basic`. |
  108. | `BKT_PROJECT` / `BKT_WORKSPACE` / `BKT_REPO` | Default Data Center project, Cloud workspace, and repository. |
  109. | `BKT_CONFIG_DIR` | Config directory (default: the per-OS location above). |
  110. | `BKT_OAUTH_CLIENT_ID` / `BKT_OAUTH_CLIENT_SECRET` | Your own Bitbucket Cloud OAuth consumer for `--web`; set both. |
  111. | `BKT_ALLOW_INSECURE_STORE` | `1` allows the encrypted file store when no keychain exists. |
  112. | `BKT_KEYRING_TIMEOUT` | Keychain operation timeout, for example `2m`. |
  113. | `BKT_KEYRING_COLLECTION` | Secret Service collection (Linux). |
  114. | `BKT_HTTP_DEBUG` | `1` logs each request URL and response status. |
  115. ## Use it
  116. 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`.
  117. ```bash
  118. bkt context create cloud --host api.bitbucket.org --workspace myteam --set-active
  119. bkt context list
  120. ```
  121. **Repositories**
  122. ```bash
  123. bkt repo list --limit 20
  124. bkt repo view platform-api
  125. bkt repo create data-pipeline --description "Data ingestion" --project DATA # Data Center
  126. bkt repo create frontend-app --workspace myteam --cloud-project WEB # Cloud
  127. bkt repo clone platform-api --project DATA --ssh
  128. bkt repo browse --project DATA --repo platform-api
  129. bkt repo downloads upload before.png after.png # Cloud: host images for PR descriptions
  130. ```
  131. **Pull requests**
  132. ```bash
  133. bkt pr list --state OPEN --limit 10
  134. bkt pr create --title "feat: cache" --source feature/cache --target main --reviewer alice
  135. bkt pr checks 42 --wait --timeout 5m # wait for builds, with backoff
  136. bkt pr mergeability 42 --json # Cloud: read-only merge checks
  137. bkt pr comments 42 --details # threads with file/line anchors
  138. bkt pr comments resolve 42 1001
  139. bkt pr merge 42 --message "merge: feature/cache"
  140. ```
  141. `pr mergeability` reports `mergeable` (`MERGEABLE`, `CONFLICTING`, `UNKNOWN`),
  142. `mergeStateStatus` (`CLEAN`, `DIRTY`, `BLOCKED`, `UNKNOWN`), and the full Cloud
  143. checks with their blocking flags. API errors print `UNKNOWN` and exit nonzero.
  144. `CLEAN` reflects the available checks, which cannot guarantee an actual merge.
  145. Use `--json --jq '{mergeable, mergeStateStatus}'` to select just the summary.
  146. **Issues.** Atlassian removed Bitbucket Cloud Issues in August 2026, and Data Center never had them; track issues in Jira.
  147. **Pipelines, branches, permissions, webhooks**
  148. ```bash
  149. bkt pipeline run --workspace myteam --repo api --ref main --var ENV=staging
  150. bkt pipeline run --ref master --selector-type custom --selector-pattern deploy-to-production
  151. bkt status pipeline {pipeline-uuid}
  152. bkt branch create release/1.9 --from main
  153. bkt perms repo list --project DATA --repo platform-api
  154. bkt webhook create --name "CI" --url https://ci.example.com/hook --event repo:refs_changed
  155. bkt status rate-limit
  156. ```
  157. **Anything else.** `bkt api` calls any REST endpoint with your stored credentials:
  158. ```bash
  159. bkt api /rest/api/1.0/projects --param limit=100 --json # Data Center
  160. bkt api /repositories --param workspace=myteam --field pagelen=50 # Cloud
  161. ```
  162. **Output for scripts.** Commands accept `--json`, `--yaml`, `--jq <expr>`, and `--template <go-template>`.
  163. **Extensions.** `bkt extension install <git-url>` adds a `bkt-<name>` command; `bkt extension exec <name>` runs it.
  164. **Shell completion.** `bkt completion bash|zsh|fish|powershell`. The Homebrew core formula installs completions for you.
  165. The full command reference, generated from `bkt --help`, is in [`skills/bkt/rules/`](skills/bkt/rules/).
  166. ## Coding agents
  167. **Agent skill.** The `bkt` skill teaches Claude Code, Codex, and other agents to use `bkt`:
  168. ```bash
  169. npx skills add avivsinai/bitbucket-cli -g -y
  170. ```
  171. 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/`.
  172. **MCP server.** `bkt mcp serve` exposes read-only Bitbucket tools over MCP stdio for one pinned context:
  173. ```bash
  174. claude mcp add bitbucket -- bkt mcp serve
  175. ```
  176. **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):
  177. ```bash
  178. bkt skill install myteam/agent-skills # list what a repository publishes
  179. bkt skill install myteam/agent-skills code-review@v1.2.0 --agent claude-code --scope user
  180. bkt skill list
  181. bkt skill update --all
  182. bkt skill publish --tag v1.2.0 # validate and tag your own skills
  183. ```
  184. `--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.
  185. ## Troubleshooting
  186. - `BKT_HTTP_DEBUG=1 bkt <command>` prints each request URL and response status.
  187. - `bkt auth status` shows each host, its auth method, and OAuth expiry.
  188. - `bkt auth doctor` diagnoses keychain prompts and timeouts.
  189. ## Project
  190. - [Contributing](CONTRIBUTING.md): build, test, and pull request workflow
  191. - [Security policy](SECURITY.md) and [security operations](docs/SECURITY.md)
  192. - [Changelog](CHANGELOG.md) · [Versioning](docs/VERSIONING.md) · [Privacy](docs/PRIVACY.md)
  193. - Questions and bugs: [GitHub issues](https://github.com/avivsinai/bitbucket-cli/issues)
  194. `bkt` is available under the [MIT License](LICENSE).

Version history

  • v0.40.211/18/2026

  • v0.40.111/17/2026

  • v0.39.011/15/2026

  • v0.38.111/11/2026

  • v0.37.010/25/2026

  • v0.36.010/23/2026

  • v0.35.210/21/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.