---
name: Bitbucket CLI
slug: bitbucket-cli
category: DevOps
description: Bitbucket CLI lets you manage Bitbucket Data Center and Cloud from the terminal. Use it for repositories, pull requests, branches, issues, webhooks, pipelines, auth, and JSON/YAML scripting.
github: "https://github.com/avivsinai/bitbucket-cli/tree/master/skills/bkt"
language: Go
stars: 200
forks: 44
install: "npx degit https://github.com/avivsinai/bitbucket-cli/tree/master/skills/bkt ~/.claude/skills/bkt"
installs_to: ~/.claude/skills/bkt
source_path: skills/bkt/SKILL.md
collection_size: 2
category_size: 973
collection_url: "https://dirskills.com/collections/avivsinai/bitbucket-cli"
added: 2026-09-05T05:30:52.850Z
last_synced: 2026-09-05T05:30:52.850Z
canonical_url: "https://dirskills.com/skills/bitbucket-cli"
---

# Bitbucket CLI

Bitbucket CLI lets you manage Bitbucket Data Center and Cloud from the terminal. Use it for repositories, pull requests, branches, issues, webhooks, pipelines, auth, and JSON/YAML scripting.

**Install:**

```bash
npx degit https://github.com/avivsinai/bitbucket-cli/tree/master/skills/bkt ~/.claude/skills/bkt
```

## README

# Bitbucket CLI (bkt)

`bkt` is a unified CLI for **Bitbucket Data Center** and **Bitbucket Cloud**. It mirrors `gh` ergonomics and provides structured JSON/YAML output for automation.

## Before You Start

**1. Verify installation** — always check before running any `bkt` command:

```bash
bkt --version
```

If not installed:

| Platform | Command |
|----------|---------|
| macOS/Linux | `brew install avivsinai/tap/bitbucket-cli` |
| Windows | `scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket && scoop install bitbucket-cli` |
| Go | `go install github.com/avivsinai/bitbucket-cli/cmd/bkt@latest` |
| Binary | Download from [GitHub Releases](https://github.com/avivsinai/bitbucket-cli/releases) |

**2. Check authentication** — most commands require an active session:

```bash
bkt auth status
```

**Bitbucket Cloud Token Requirements:**
- Create an "API token with scopes" (not a general API token)
- Select **Bitbucket** as the application
- Required scope: **Account: Read** (`read:user:bitbucket`)
- Additional scopes as needed: Repositories, Pull requests, Issues

For config-free use in containers and CI pipelines, see [headless authentication](rules/headless.md).

If not authenticated, log in:

```bash
# Data Center (PAT-based)
bkt auth login https://bitbucket.example.com --username alice --token <PAT>

# Bitbucket Cloud — OAuth (official binaries open browser out of the box)
bkt auth login https://bitbucket.org --kind cloud --web

# Bitbucket Cloud — API token (--web-token opens Atlassian's token creation page)
bkt auth login https://bitbucket.org --kind cloud --web-token
```

For source and Nix builds, set `BKT_OAUTH_CLIENT_ID` and `BKT_OAUTH_CLIENT_SECRET` env vars before running `--web`.

**3. Set up a context** — contexts bind a host to a project/workspace and optional default repo, so you don't repeat flags on every command:

```bash
# Data Center
bkt context create dc-prod --host bitbucket.example.com --project ABC --set-active

# Cloud
bkt context create cloud-team --host bitbucket.org --workspace myteam --set-active
```

## Platform Awareness

Some commands are **Data Center only** or **Cloud only** — check the command reference for `*(DC)*` and `*(Cloud)*` badges. Key splits:

| Feature | Data Center | Cloud |
|---------|:-----------:|:-----:|
| Pull requests | yes | yes |
| Repositories | yes | yes |
| Branches (list) | yes | yes |
| Branches (create/delete/protect) | yes | — |
| Issues | — | yes |
| Pipelines | — | yes |
| Permissions | yes | — |
| Webhooks | yes | yes |
| Auto-merge, tasks, reactions | yes | — |
| Variables | — | yes |
| Skill search | — | yes |

When a user's context is DC, do not suggest Cloud-only commands (and vice versa). If the platform is unknown, ask or check with `bkt auth status`.

## Common Workflows

### Create a PR from the current branch

```bash
bkt pr create --title "feat: add caching" --target main
```

Source branch, title, and target default to sensible values from git state. Add `--draft` for work-in-progress, `--reviewer alice` to request review.

### Review cycle

```bash
bkt pr checks 42 --wait          # Wait for CI to pass
bkt pr approve 42                # Approve
bkt pr merge 42                  # Merge (closes source branch by default)
```

### Checkout a colleague's PR locally

```bash
bkt pr checkout 42               # Creates pr/42 branch
```

### Structured output for scripting

All commands support `--json`, `--yaml`, `--jq`, and `--template`:

```bash
bkt pr list --mine --json | jq '.pull_requests[].title'
```

### Raw API escape hatch

For endpoints without a dedicated command:

```bash
bkt api /rest/api/1.0/projects --param limit=100 --json
```

### Search for Agent Skills in Bitbucket Cloud

```bash
bkt skill search "code review"
bkt skill search "review repo:agent-skills" --workspace myteam --json
```

Search is workspace-scoped and returns only `SKILL.md` files. It is not
available for Bitbucket Data Center because 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.

## Global Flags

Every command accepts these inherited flags:

| Flag | Short | Purpose |
|------|-------|---------|
| `--context` | `-c` | Use a specific named context |
| `--json` | | JSON output |
| `--yaml` | | YAML output |
| `--jq` | | Apply a jq expression (requires `--json`) |
| `--template` | | Render with Go template |

## References

- [headless / env vars](rules/headless.md) — Config-free CI/container auth (BKT_TOKEN, BKT_HOST) and full env var reference

<!-- auto-generated by cmd/docgen — do not edit below this line -->

- [admin](rules/admin.md) — Administrative operations for Bitbucket *(DC)*
- [auth](rules/auth.md) — Manage Bitbucket authentication credentials
- [branch](rules/branch.md) — Inspect and manage branches
- [commit](rules/commit.md) — Work with commits
- [context](rules/context.md) — Manage Bitbucket CLI contexts
- [extension](rules/extension.md) — Manage bkt CLI extensions
- [issue](rules/issue.md) — Work with Bitbucket Cloud issues *(Cloud)*
- [mcp](rules/mcp.md) — Model Context Protocol server for agents
- [perms](rules/perms.md) — Manage Bitbucket permissions *(DC)*
- [pipeline](rules/pipeline.md) — Run and inspect Bitbucket Cloud pipelines *(Cloud)*
- [pr](rules/pr.md) — Manage pull requests
- [project](rules/project.md) — Work with Bitbucket projects *(DC)*
- [repo](rules/repo.md) — Work with Bitbucket repositories
- [skill](rules/skill.md) — Install and manage agent skills
- [status](rules/status.md) — Inspect commit and pull request statuses
- [variable](rules/variable.md) — Manage pipeline variables *(Cloud)*
- [webhook](rules/webhook.md) — Manage Bitbucket webhooks
- [other](rules/other.md) — api

<!-- end auto-generated -->