{ "markdown": "# bkt – Bitbucket CLI\n\n

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

\n\n[![CI](https://github.com/avivsinai/bitbucket-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/avivsinai/bitbucket-cli/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/avivsinai/bitbucket-cli/graph/badge.svg)](https://codecov.io/gh/avivsinai/bitbucket-cli)\n[![Release](https://img.shields.io/github/v/release/avivsinai/bitbucket-cli?cache=none)](https://github.com/avivsinai/bitbucket-cli/releases)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/avivsinai/bitbucket-cli/badge)](https://scorecard.dev/viewer/?uri=github.com/avivsinai/bitbucket-cli)\n[![Go Reference](https://pkg.go.dev/badge/github.com/avivsinai/bitbucket-cli.svg)](https://pkg.go.dev/github.com/avivsinai/bitbucket-cli)\n[![License](https://img.shields.io/github/license/avivsinai/bitbucket-cli?cache=none)](LICENSE)\n\n`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.\n\nThis project (`github.com/avivsinai/bitbucket-cli`, binary `bkt`) is unrelated to the Rust [`bkt`](https://github.com/dimo414/bkt) subprocess-caching tool and to the [Bitbucket Enterprise CLI](https://github.com/swisscom/bitbucket-cli) and other same-named `bitbucket-cli` packages.\n\n

\n \"Recorded\n

\n\n```bash\nbrew install avivsinai/tap/bitbucket-cli\nbkt --help\n```\n\nRecorded from a real `bkt --help` run — no Bitbucket login or token required. Other installers: [WinGet](#winget-windows), [Scoop](#scoop-windows), [Nix](#nix-nixos--nix-darwin--linux--macos), [Go](#go-install), [binaries](#binary-downloads).\n\n**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.\n\n## Installation\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew install avivsinai/tap/bitbucket-cli\n```\n\n### WinGet (Windows)\n\n```powershell\nwinget install AvivSinai.Bitbucket-CLI\n```\n\n### Scoop (Windows)\n\n```powershell\nscoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket\nscoop install bitbucket-cli\n```\n\n### Go Install\n\n```bash\ngo install github.com/avivsinai/bitbucket-cli/cmd/bkt@latest\n```\n\nThis installs `bkt` to `$GOPATH/bin` (or `$HOME/go/bin` by default). Ensure the directory is in your `$PATH`.\n\n### Nix (NixOS / nix-darwin / Linux / macOS)\n\nRun the latest `master` without installing:\n\n```bash\nnix run github:avivsinai/bitbucket-cli -- --version\n```\n\nInstall into your user profile:\n\n```bash\nnix profile install github:avivsinai/bitbucket-cli\n```\n\nPin to a specific tag or commit by appending a ref (e.g. `github:avivsinai/bitbucket-cli/v1.2.3`).\n\nDon't have Nix yet? See [nixos.asia/en/install](https://nixos.asia/en/install) for a quick setup guide (installs Nix with flakes enabled out of the box).\n\n### Binary Downloads\n\nDownload pre-built binaries for your platform from the [releases page](https://github.com/avivsinai/bitbucket-cli/releases/latest).\nThe `.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.\n\nOfficial 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.\n\n### Bitbucket Pipelines\n\n`bkt` supports fully config-free headless use via environment variables. Set `BKT_TOKEN` and `BKT_HOST` as secured [repository variables](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/) — no prior `bkt auth login` or `bkt context create` step required.\n\n```yaml\npipelines:\n default:\n - step:\n name: Open PR\n script:\n - export BKT_VERSION=\"0.26.0\" # pin to a released version\n - 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/\n - bkt pr create --title \"Auto PR\" --source \"$BITBUCKET_BRANCH\"\n```\n\n### Environment Variables\n\nAll `bkt` behaviour can be configured via environment variables, which is especially useful in containers and CI/CD pipelines.\n\n| Variable | Description |\n|---|---|\n| `BKT_TOKEN` | Authentication token. Bypasses keyring storage entirely. |\n| `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. |\n| `BKT_USERNAME` | Username for basic authentication in headless mode. Required for Cloud basic auth; not required for bearer auth. |\n| `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. |\n| `BKT_PROJECT` | Default Data Center project key (headless mode). |\n| `BKT_WORKSPACE` | Default Bitbucket Cloud workspace (headless mode). |\n| `BKT_REPO` | Default repository slug (headless mode). |\n| `BKT_CONFIG_DIR` | Override the config file directory (default: `$XDG_CONFIG_HOME/bkt`). |\n| `BKT_HTTP_DEBUG` | Set to `1` to log HTTP request URLs and response status codes. |\n| `BKT_ALLOW_INSECURE_STORE` | Set to `1` to use encrypted file fallback when no OS keychain is available. |\n\n**Minimal headless example (Data Center):**\n\n```bash\nexport BKT_HOST=https://bitbucket.example.com\nexport BKT_TOKEN=my-personal-access-token\nexport BKT_PROJECT=MYPROJ\nexport BKT_REPO=my-service\n\nbkt pr list\nbkt pr create --title \"Automated PR\" --source feature/my-branch\n```\n\n**Minimal headless example (Bitbucket Cloud):**\n\n```bash\n# User API token — basic auth\nexport BKT_HOST=https://bitbucket.org\nexport BKT_TOKEN=my-api-token\nexport BKT_USERNAME=me@example.com\nexport BKT_WORKSPACE=my-workspace\nexport BKT_REPO=my-repo\n\nbkt pr list\n\n# Repository, project, or workspace access token — bearer auth\nexport BKT_TOKEN=my-resource-access-token\nexport BKT_AUTH_METHOD=bearer\nunset BKT_USERNAME\n\nbkt pr list\n```\n\nResource access tokens are not associated with a user. Commands that require\nauthenticated-user identity, such as cross-repository `bkt pr list --mine`,\nstill require user API-token or OAuth credentials.\n\n### From Source\n\n```bash\ngit clone https://github.com/avivsinai/bitbucket-cli.git\ncd bitbucket-cli\nmake build # produces ./bin/bkt\n./bin/bkt --help\n```\n\n### Claude Code / Codex Skill\n\nInstall the `bkt` skill to give Claude Code or Codex CLI native Bitbucket knowledge:\n\n
\nVia skills (Recommended)\n\nUsing [Vercel's skills CLI](https://github.com/vercel-labs/add-skill):\n\n```bash\nnpx skills add avivsinai/bitbucket-cli -g -y\n```\n\n
\n\n
\nVia skild registry\n\n```bash\nnpx skild install @avivsinai/bkt -t claude -y\n```\n\n
\n\n
\nVia Skills Marketplace\n\n> **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.\n\n```bash\n/plugin marketplace add avivsinai/skills-marketplace\n/plugin install bkt@avivsinai-marketplace\n```\n\n
\n\n
\nManual install\n\n```bash\ngit clone https://github.com/avivsinai/bitbucket-cli.git\ncp -r bitbucket-cli/skills/bkt ~/.claude/skills/\n```\n\n
\n\n## Getting started\n\nAfter installation, verify it works:\n\n```bash\nbkt --help\n```\n\n### 1. Authenticate against Bitbucket Data Center or Cloud\n\n#### Bitbucket Data Center\n\n```bash\n# Guided flow: opens browser to create a Personal Access Token\nbkt auth login https://bitbucket.mycorp.example --web-token\n\n# Or provide credentials directly\nbkt auth login https://bitbucket.mycorp.example --username alice --token \n```\n\nCreate a **Personal Access Token (PAT)** in Bitbucket Data Center:\n1. Go to **Profile picture → Manage account → Personal access tokens**\n2. Click **Create a token**\n3. Grant permissions: **Repository Read**, **Repository Write**, **Project Read**\n4. Copy the token (you won't see it again)\n\n#### Bitbucket Cloud\n\n```bash\n# Browser OAuth flow for Bitbucket Cloud\nbkt auth login https://bitbucket.org --kind cloud --web\n\n# Or provide credentials directly\nbkt auth login https://bitbucket.org --kind cloud --username --token \n```\n\nCreate an **API token with scopes** for Bitbucket Cloud:\n1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)\n2. Click **Create and manage API tokens** → **Create API token with scopes**\n3. Name your token and set an expiry date\n4. **Select \"Bitbucket\" as the application** (required!)\n5. Grant scopes:\n - **Account: Read (`read:user:bitbucket`)** — Required for authentication\n - **Repositories: Read, Write** — For repo commands\n - **Pull requests: Read, Write** — For PR commands\n - **Issues: Read, Write** — For issue commands (optional)\n6. Click **Create** and copy the token immediately\n\n> **Warning:** General Atlassian API tokens won't work. You must select \"Bitbucket\" as the application when creating the token.\n\n> **Note:** Use your **Atlassian account email** as the username (not your Bitbucket username).\n\n
\nLegacy: App passwords (deprecated)\n\nApp 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:\n\n```bash\nbkt auth login https://bitbucket.org --kind cloud --username --token \n```\n\nNote: For app passwords, use your **Bitbucket username** (not email).\n\n
\n\n#### Credential storage\n\nAccess tokens are stored in your OS keychain (Keychain Access on macOS, Windows Credential Manager, or\nSecret Service/KWallet on Linux) while host metadata lives in\n`$XDG_CONFIG_HOME/bkt/config.yml`. Pass `--allow-insecure-store` (or set\n`BKT_ALLOW_INSECURE_STORE=1`) to permit the encrypted file backend on systems\nwithout a native keychain.\n\nIf your keyring requires an interactive unlock prompt, you can increase the keyring timeout via\n`BKT_KEYRING_TIMEOUT` (for example `BKT_KEYRING_TIMEOUT=2m`).\n\n##### macOS note: Keychain prompts after `brew upgrade`\n\nOn macOS, every `brew upgrade bkt` may trigger one Keychain prompt because the\nstored item's ACL is tied to the installed binary. Re-run `bkt auth login` once\nafter the upgrade to refresh the ACL, then subsequent invocations should not\nprompt. Releases pin the Designated Requirement to the bundle identifier, so\nthe refresh is only needed once. Run `bkt auth doctor` to diagnose prompts\nthat persist beyond that; it never reads the stored secret.\n\n### 2. Create and activate a context\n\n#### Bitbucket Data Center\n\n```bash\nbkt context create dc-prod --host bitbucket.mycorp.example --project ABC --set-active\nbkt context list\n```\n\n#### Bitbucket Cloud\n\n```bash\nbkt context create cloud-prod --host api.bitbucket.org --workspace myteam --set-active\nbkt context list\n```\n\n> **Tip:** Run `bkt auth status` to see configured hosts and the exact host value to use with `--host`.\n\nContexts capture the host mapping, default project/workspace, and optional default repository for commands.\n\n### 3. Work with repositories\n\n```bash\nbkt repo list --limit 20\nbkt repo list --workspace myteam --limit 10 # Cloud workspace override\nbkt repo view platform-api\nbkt repo create data-pipeline --description \"Data ingestion\" --project DATA\nbkt repo create frontend-app --workspace myteam --cloud-project WEB\nbkt repo browse --project DATA --repo platform-api\nbkt repo clone platform-api --project DATA --ssh\n```\n\n`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}`.\nFor `repo create`, `--project`, `--forkable`, `--default-branch`, and `--scm` are Data Center flags; `--workspace` and `--cloud-project` are Cloud flags. Host-specific create flags are rejected when they would otherwise be ignored.\n\n### 4. Pull request workflows\n\n```bash\nbkt pr list --state OPEN --limit 10\nbkt pr create --title \"feat: cache\" --source feature/cache --target main --reviewer alice\nbkt pr merge 42 --message \"merge: feature/cache\"\nbkt pr checks 42 # Show build/CI status\nbkt pr checks 42 --wait # Wait for builds to complete\nbkt pr checks 42 --wait --timeout 5m # Wait with timeout\nbkt pr checks 42 --wait --max-interval 1m # Custom backoff cap\nbkt pr comments 42 --details # Review PR comments and thread IDs\nbkt pr comments resolve 42 1001 # Resolve a top-level comment thread\nbkt pr comments reopen 42 1001 # Reopen a resolved comment thread\nbkt pr comments delete 42 1001 # Delete a PR comment\n```\n\nThe 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.\nFor comment thread state changes, pass the top-level thread comment ID; replies\ncannot be resolved or reopened directly.\n\n### 5. Issue tracking (Bitbucket Cloud only)\n\n```bash\nbkt issue list --state open --kind bug # List open bugs\nbkt issue view 42 --comments # View issue with comments\nbkt issue create -t \"Login broken\" -k bug -p major\nbkt issue edit 42 --assignee \"{abc-123}\" --priority critical\nbkt issue close 42 # Close an issue\nbkt issue reopen 42 # Reopen a closed issue\nbkt issue comment 42 -b \"Fixed in v1.2.0\" # Add a comment\nbkt issue status # Show your assigned/created issues\n\n# Attachments\nbkt issue attachment list 42 # List attachments\nbkt issue attachment upload 42 screenshot.png # Upload file(s)\nbkt issue attachment download 42 --all # Download all attachments\nbkt issue attachment delete 42 old-file.txt # Delete an attachment\n```\n\nNote: The issue tracker is only available for Bitbucket Cloud. Bitbucket Data Center uses Jira for issue tracking.\n\n### 6. Branch, permission, webhook, pipeline, and extension management\n\n```bash\nbkt branch list --workspace myteam # Cloud branch listing\nbkt branch create release/1.9 --from main # Data Center branch utils\nbkt perms repo list --project DATA --repo platform-api\nbkt webhook create --name \"CI\" --url https://ci.example.com/hook --event repo:refs_changed\nbkt pipeline run --workspace myteam --repo api --ref main --var ENV=staging\nbkt pipeline run --ref master --selector-type custom --selector-pattern deploy-to-production\nbkt extension install https://github.com/example/bkt-hello.git\nbkt extension exec hello -- --flag=1\nbkt status pipeline {pipeline-uuid}\nbkt status rate-limit\n```\n\nBranch 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.\n\nExtensions 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.\n\n### 7. Agent skills\n\n`bkt skill` installs [Agent Skills](https://agentskills.io/specification) from Bitbucket repositories, mirroring [`gh skill`](https://github.com/cli/cli#agent-skills) so the same workflow works for skills hosted on Bitbucket Cloud and Data Center.\n\n```bash\nbkt skill install myteam/agent-skills # List the skills a repository publishes\nbkt skill install myteam/agent-skills code-review # Install one skill\nbkt skill install PROJ/agent-skills code-review # Data Center, addressed by project key\nbkt skill install myteam/agent-skills code-review@v1.2.0 --agent claude-code --scope user\nbkt skill list # Show what is installed, and from where\nbkt skill preview myteam/agent-skills code-review # Inspect before installing\nbkt skill update --all # Refresh everything that changed\nbkt skill search \"code review\" # Search SKILL.md files across a Cloud workspace\n```\n\nIf your repository publishes skills, `bkt skill publish` validates them and tags a version:\n\n```bash\nbkt skill publish --dry-run # Validate without tagging\nbkt skill publish --fix # Strip committed install metadata\nbkt skill publish --tag v1.2.0 # Tag the current commit as a version\n```\n\nSkills are discovered with the specification's conventions (`skills/*/SKILL.md`, `skills/{author}/*/SKILL.md`, `plugins/*/skills/*/SKILL.md`, root-level `*/SKILL.md`, and a `skills/` directory nested under a prefix). Use `--allow-hidden-dirs` to include copies kept in `.claude/skills/` or `.agents/skills/`.\n\nPlacement follows the target agent: `--agent` selects one of the supported hosts (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and many more; run `bkt skill install --help` for the full list) and `--scope project|user` chooses between the current repository and your home directory. The default agent, `universal`, writes to the shared `.agents/skills` directory that most agents read. `--dir` overrides both.\n\nInstalled skills record their origin in `SKILL.md` frontmatter under `metadata.bitbucket-*`, which is what `bkt skill update` compares against the source repository. Because Bitbucket exposes no per-directory tree hash, the recorded version is the latest commit that touched the skill directory. Installing with `@version` or `--pin` pins the skill, and `bkt skill update` then skips it until you pass `--unpin`.\n\n`bkt skill search` is available for Bitbucket Cloud only. It searches `SKILL.md` files across the workspace selected by `--workspace` or the active context, and supports Bitbucket query terms such as `repo:agent-skills`. Bitbucket Data Center has no public workspace code-search API. Atlassian has announced that the [Cloud code-search REST endpoint](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-other-operations/#api-workspaces-workspace-search-code-get) will be deprecated on November 1, 2026.\n\n### Structured output & raw API access\n\nEvery command supports the global `--json` and `--yaml` flags for automation-ready output.\n\nFor endpoints that are not yet wrapped, reach directly for the API escape hatch:\n\n```bash\nbkt api /rest/api/1.0/projects --param limit=100 --json\nbkt api /repositories --param workspace=myteam --field pagelen=50\n```\n\n## Security\n\nThis 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)).\n\nFound a security issue? See our [security policy](SECURITY.md) for responsible disclosure.\n\n## Development\n\n### Project Layout\n\n```\ncmd/bkt/ # CLI entry point\ninternal/bktcmd/ # Main() wiring (factory + root command)\ninternal/build/ # Version metadata (overridden via ldflags)\ninternal/config/ # Context and host configuration\ninternal/remote/ # Git remote parsing utilities\npkg/cmd/ # Cobra command implementations (auth, repo, pr, ...)\npkg/cmdutil/ # Shared command helpers and factory wiring\npkg/iostreams/ # IO stream abstractions\npkg/bbdc/ # Bitbucket Data Center client implementation\npkg/bbcloud/ # Bitbucket Cloud client implementation\npkg/format/ # Output rendering helpers\npkg/httpx/ # Shared HTTP client and retry logic\n```\n\n### Building & Testing\n\n```bash\nmake build # Build the binary to ./bin/bkt\nmake test # Run unit tests\nmake fmt # Format code\nmake lint # Run linters\nmake tidy # Tidy go modules\nmake check-skills # Verify generated skill mirrors\nmake sync-skills # Regenerate skill mirrors from skills/bkt\n```\n\n`go test ./...` runs fast smoke coverage that wires the CLI against an in-memory Bitbucket mock (see `pkg/cmd/smoke/cli_smoke_test.go`).\n\n`skills/bkt/` is canonical. After editing it, run `make sync-skills` to refresh\nthe committed `.claude/skills/bkt/` and `.agents/skills/bkt/` mirrors.\n\n## Troubleshooting\n\n### Debug HTTP Requests\n\nTo see API request URLs and response status codes, set the `BKT_HTTP_DEBUG` environment variable:\n\n```bash\nBKT_HTTP_DEBUG=1 bkt pipeline view 10\n```\n\nThis outputs request method/URL and response status, useful for diagnosing API errors.\n\n## Support\n\n- **Questions / Ideas**: File an [issue](https://github.com/avivsinai/bitbucket-cli/issues/new?template=feature_request.md)\n- **Bug Reports**: File an [issue](https://github.com/avivsinai/bitbucket-cli/issues/new?template=bug_report.md)\n\n## License\n\n`bkt` is available under the [MIT License](LICENSE).\n", "bytes": 21759, "sha": "06ab3990d16e603ea4ab9edb631a79da21befc03cf061b62fe10272fa227e32b", "repo_slug": "avivsinai/bitbucket-cli", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/skl_avivsinai_bitbucket_cli_bkt_ecdb8fc3/readme" }