Skip to content
Bitbucket CLI Bitbucket CLI

AI Agent Integration - Claude Code, Cursor, Windsurf & More

Manage pull requests, repositories, and code reviews through natural conversation. Tell your AI assistant “Create a PR for this branch” and it handles the commands, flags, and context automatically.

Quick Start

Section titled “Quick Start”

Pick your editor and paste the command:

Run this in your project root:

Terminal window
mkdir -p .claude/skills/bb-cli && cat > .claude/skills/bb-cli/SKILL.md << 'SKILL'
---
name: bb-cli
description: >
  Bitbucket Cloud CLI. Use when the user wants to create, list, review,
  merge, or manage pull requests, repositories, authentication, or
  configuration via the `bb` command.
argument-hint: "[command or question]"
allowed-tools: Bash(bb *), Read, Grep, Glob
---


# Bitbucket CLI (`bb`)


CLI for Bitbucket Cloud. Package: `@pilatos/bitbucket-cli`.


## Available commands


!`bb --help`


## Key workflows


**Create PR:** `bb pr create -t "title" -b "description"`
**List PRs:** `bb pr list` (add `--mine` for your reviews, `--json` for scripts)
**Review:** `bb pr checkout <id>` → `bb pr diff <id>` → `bb pr approve <id>`
**Merge:** `bb pr merge <id> --strategy squash --close-source-branch`
**Draft:** `bb pr create -t "WIP" --draft` → later `bb pr ready <id>`
**Comments:** `bb pr comments list <id>` / `bb pr comments add <id> "text"`
**Repos:** `bb repo list`, `bb repo clone workspace/repo`, `bb repo view`


## Tips


- Auto-detects workspace/repo from git remotes; override with `-w` / `-r`
- All commands support `--json` for structured output
- Merge strategies: `merge-commit`, `squash`, `fast-forward`
SKILL


echo "✓ Skill installed. Restart Claude Code to activate."

Restart Claude Code and try: “List my open PRs”

Example Workflows

Section titled “Example Workflows”

These show what’s possible once your AI assistant knows about bb. Natural language works — exact phrasing doesn’t matter.

Create and submit a PR

Section titled “Create and submit a PR”
You: Push my changes and create a PR titled "Add input validation"
      with a description of what changed


AI:   [Runs: git push -u origin feat/input-validation]
      [Runs: bb pr create -t "Add input validation" \
        -b "Adds server-side validation for email and password fields.
        Includes unit tests and updates the API docs."]


      ✅ Created PR #47
      https://bitbucket.org/acme/api/pull-requests/47

Review multiple PRs at once

Section titled “Review multiple PRs at once”
You: Show me all open PRs and summarize which ones are ready to merge


AI:   [Runs: bb pr list --json]
      [Runs: bb pr diff 42, bb pr diff 45, bb pr diff 46]


      3 open PRs:


      • #42 "Fix login timeout" — 12 lines, 2 approvals, CI passing. Ready.
      • #45 "Refactor auth module" — 340 lines, no reviews, CI failing. Needs work.
      • #46 "Update README" — 3 lines, 1 approval. Ready.


      Want me to merge #42 and #46?

Full review-and-merge cycle

Section titled “Full review-and-merge cycle”
You: Check out PR 42, review the diff, and if it looks good,
     approve and squash-merge it


AI:   [Runs: bb pr checkout 42]
      Checked out PR #42 on branch fix/login-timeout.


      [Runs: bb pr diff 42]
      Changes look clean — fixes the timeout by increasing the
      retry limit from 3 to 5, with a new test covering the edge case.


      [Runs: bb pr approve 42]
      ✅ Approved.


      [Runs: bb pr merge 42 --strategy squash --close-source-branch]
      ✅ Merged PR #42 with squash strategy. Source branch deleted.

Draft PR workflow

Section titled “Draft PR workflow”
You: Create a draft PR for my work-in-progress


AI:   [Runs: bb pr create -t "WIP: New dashboard" --draft]
      ✅ Created draft PR #48


You: Mark PR 48 as ready and add Alice as reviewer


AI:   [Runs: bb pr ready 48]
      [Runs: bb pr reviewers add 48 {alice-uuid}]
      ✅ PR #48 is ready for review. Alice added as a reviewer.

Security

Section titled “Security”

Your AI assistant never sees the raw token — it calls bb commands, and the CLI handles authentication internally. The allowed-tools field in the Claude Code skill restricts the AI to only running bb commands and reading files — no arbitrary shell access.

For CI/CD or shared environments, use environment variables:

Terminal window
export BB_USERNAME="your-username"
export BB_API_TOKEN="your-api-token"
bb auth login   # Reads from env vars automatically

Required API token scopes

Section titled “Required API token scopes”
ScopeRequired for
read:user:bitbucketbb auth status — verify identity
read:repository:bitbucketbb repo list, bb repo view — browse repos
write:repository:bitbucketbb repo create — create repos
admin:repository:bitbucketbb repo delete — delete repos (optional)
read:pullrequest:bitbucketbb pr list, bb pr view, bb pr diff — browse PRs
write:pullrequest:bitbucketbb pr create, bb pr merge, bb pr approve — manage PRs

Troubleshooting

Section titled “Troubleshooting”
IssueSolution
”Not authenticated”Run bb auth login or set BB_USERNAME + BB_API_TOKEN env vars
Claude doesn’t use bbRestart Claude Code after creating the skill file. Check /bb-cli shows in the slash menu
”Could not determine repo”Run from a git repo with a Bitbucket remote, or pass -w/-r flags explicitly
Skill not auto-activatingInvoke manually with /bb-cli, or check the description field in SKILL.md
Cursor rule not loadingEnsure the file is at .cursor/rules/bb-cli.mdc with valid frontmatter. Restart Cursor
opencode ignoring AGENTS.mdEnsure the file is in the project root (not a subdirectory). Restart opencode
bb command not foundInstall with npm install -g @pilatos/bitbucket-cli. Requires Bun 1.0+ runtime
AI using wrong flagsTell the AI to run bb <command> --help first
Windsurf not picking up rulesEnsure .windsurfrules is in the project root. Restart Windsurf
Section titled “Related Guides”