Skip to content
Bitbucket CLIBitbucket CLI

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

Drop a skill or rules file into your project and your coding assistant drives Bitbucket through bb. The templates below cover Claude Code, opencode, Cursor, and Windsurf.

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>` (add `--unresolved` to see open threads), `bb pr comments add <id> "text"`, `bb pr comments view <pr-id> <comment-id>`
**Review threads:** `bb pr comments reply <pr-id> <comment-id> "text"` → `bb pr comments resolve <pr-id> <comment-id>` (`unresolve` reopens); `bb pr comments edit <pr-id> <comment-id> "text"`, `bb pr comments delete <pr-id> <comment-id>`
**Repos:** `bb repo list`, `bb repo clone workspace/repo`, `bb repo view`
**CI/CD:** `bb pipeline list`, `bb pipeline run --branch main`, `bb pipeline view/logs/stop <id>`
**Commits:** `bb commit list`, `bb commit view <sha>`; build statuses: `bb status list <sha>`, `bb status set <sha> --key CI --state SUCCESSFUL`
**Snippets:** `bb snippet list/view/create/edit/delete/watch/unwatch`, plus `bb snippet comments`
**Workspaces & projects:** `bb workspace list/view`, `bb project list/view/create`
**Browser URLs:** `bb browse --pr <id> -n` prints the URL instead of opening it (`--json` does the same and returns `{"url": …}`)
**Raw API:** `bb api <endpoint>` — any Bitbucket 2.0 endpoint not covered above (e.g. `bb api /repositories/{workspace}/{repo}/branch-restrictions`; supports `--paginate` and `--jq`)


## 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 pull requests”

Example workflows

Section titled “Example workflows”

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.

Work an open review thread

Section titled “Work an open review thread”
You: What review comments are still open on PR 45?


AI:   [Runs: bb pr comments list 45 --unresolved]


      2 unresolved:
      • #109820 bob — "This retry loop has no upper bound."
      • #109834 bob — "Missing test for the 429 path."


You: Fix both, then reply and resolve them


AI:   [Edits src/client.ts, adds tests]
      [Runs: bb pr comments reply 45 109820 "Capped at 3 attempts in a1b2c3d."]
      [Runs: bb pr comments resolve 45 109820]
      [Runs: bb pr comments reply 45 109834 "Added a 429 retry test in a1b2c3d."]
      [Runs: bb pr comments resolve 45 109834]
      ✅ Both threads replied to and resolved.

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”

These cover the command families the templates above teach. For the full command-to-scope map, see Token Scopes.

Scope Required for
read:user:bitbucket Identity checks — bb auth status, plus resolving your own UUID for bb pr create and bb pr list --mine
read:repository:bitbucket bb repo list, bb repo view, bb commit list/view, bb status list — browse repos and commits
write:repository:bitbucket bb status set — set commit build statuses
admin:repository:bitbucket bb repo create, bb repo default-reviewers add/remove
delete:repository:bitbucket bb repo delete — delete repos (optional)
read:pullrequest:bitbucket bb pr list, bb pr view, bb pr diff, bb pr comments list — browse PRs
write:pullrequest:bitbucket bb pr create, bb pr merge, bb pr approve, bb pr comments add/reply/resolve — manage PRs
read:pipeline:bitbucket bb pipeline list, bb pipeline view, bb pipeline logs — inspect CI/CD
write:pipeline:bitbucket bb pipeline run, bb pipeline stop — control CI/CD
read:workspace:bitbucket bb workspace list, bb workspace view — discover workspaces
read:project:bitbucket bb project list, bb project view — browse projects
admin:project:bitbucket bb project create — create projects
read:snippet:bitbucket bb snippet list, bb snippet view — browse snippets
write:snippet:bitbucket bb snippet create/edit/delete/watch/unwatch — manage snippets

For read-only agents (listing and viewing), the read scopes are enough.

OAuth agents

Section titled “OAuth agents”

bb auth login defaults to OAuth, which requests a fixed scope set and never prompts you to choose:

account repository repository:admin pullrequest pullrequest:write

That covers repository and pull request work, including bb repo create and bb repo default-reviewers. It does not cover bb pipeline, bb project, bb snippet, or bb repo delete — those return 403 under OAuth. Use an API token with the scopes above if your agent needs them.

Troubleshooting

Section titled “Troubleshooting”
Issue Solution
“Not authenticated” Run bb auth login or set BB_USERNAME + BB_API_TOKEN env vars
Claude doesn’t use bb Restart 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-activating Invoke manually with /bb-cli, or check the description field in SKILL.md
Cursor rule not loading Ensure the file is at .cursor/rules/bb-cli.mdc with valid frontmatter. Restart Cursor
opencode ignoring AGENTS.md Ensure the file is in the project root (not a subdirectory). Restart opencode
bb command not found Install with npm install -g @pilatos/bitbucket-cli. Requires Bun 1.0+ runtime
AI using wrong flags Tell the AI to run bb <command> --help first
Windsurf not picking up rules Ensure .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:

URL Contents
/llms.txt Index pointing to the two content files below
/llms-full.txt Every doc page concatenated as markdown
/llms-small.txt Abridged subset (excludes Help / FAQ / Changelog) for tight context windows

All three are generated at build time, so they always match the live docs. Tools that support llms.txt find them on their own. For everything else, paste the URL into the chat — in Cursor, @https://bitbucket-cli.paulvanderlei.com/llms-full.txt.

Section titled “Related guides”