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`, `squash_fast_forward`, `rebase_fast_forward`, `rebase_merge`
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

llms.txt for IDE agents

Section titled “llms.txt for IDE agents”

The docs site publishes the llms.txt convention so agents that fetch documentation on demand (Cursor, Cline, Continue, Aider, and similar) can pull a clean markdown view of the full reference instead of scraping HTML:

URLContents
/llms.txtIndex pointing to the two content files below
/llms-full.txtEvery doc page concatenated as markdown
/llms-small.txtAbridged subset (excludes Help / FAQ / Changelog) for tight context windows

All three are generated at build time, so they always match the live docs. You don’t need to do anything to consume them — tools that support llms.txt will discover them automatically. If your tool doesn’t, paste the URL into the chat (@https://bitbucket-cli.paulvanderlei.com/llms-full.txt in Cursor, for example).

Section titled “Related Guides”