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”

Install bb and authenticate yourself first. A standalone binary needs no runtime; the npm package requires Bun 1.1.30 or newer, and Windows --jq requires Bun 1.4.2 or newer.

Terminal window
bb auth login
bb auth status
bb doctor

bb doctor --json gives an agent a pass/warn/fail row per check and exits 1 when something is broken.

Ask your assistant to run bb --help, then bb pr list --all --json. For repeated use, put these instructions in its project rules or skill file:

## Bitbucket CLI


Use `bb` for Bitbucket Cloud operations.


- Run `bb --help` and `bb <group> <command> --help` before using unfamiliar flags.
- Use `--json` after the command for structured output. Use `--all` on list
  commands that support it when the task needs every result. Add `--lean` to
  drop link noise, or `--jq <filter> --raw-output` to get plain strings.
- Workspace and repository come from the Bitbucket git remote. Pass -w and -r
  explicitly when operating outside that checkout.
- Read PRs with `bb pr view <id>`, `bb pr diff <id>`, and
  `bb pr comments list <id> --all --unresolved`.
- `bb pr checks <id>` reads every build status. `bb pr checks <id> --watch`
  waits until none is in progress and exits non-zero if any failed;
  `bb pipeline watch` does the same for a pipeline run.
- Use `bb api <endpoint>` for operations without a typed command.
- Follow the user's approval rules before posting comments, approving,
  pushing, merging, or deleting resources.
- Add `--dry-run` to a write command to show the exact request (method, URL,
  body) without sending it.
- Never read, print, or copy credentials. Ask the user to authenticate.
  Without a terminal, `bb auth login` fails with code 1001 instead of opening
  a browser.

Save the shared instructions above in .claude/skills/bb-cli/SKILL.md, with this frontmatter at the top:

---
name: bb-cli
description: Use the bb CLI to inspect and manage Bitbucket Cloud repositories and pull requests.
---

Invoke /bb-cli, or ask a question that matches its description. For a personal skill, use ~/.claude/skills/bb-cli/SKILL.md. See Claude Code skills.

Example workflows

Section titled “Example workflows”

Create and submit a PR

Section titled “Create and submit a PR”

After the user authorizes a push and PR creation:

Terminal window
git push -u origin feat/input-validation
bb pr create -t "Add input validation" -b "Validates email and password fields." --draft

Review multiple PRs at once

Section titled “Review multiple PRs at once”
Terminal window
bb pr list --all --json
bb pr view 42 --json
bb pr diff 42
bb pr comments list 42 --all --unresolved --json

The list and diff do not prove merge readiness. Inspect approvals and required checks, and follow the repository’s merge policy.

Full review-and-merge cycle

Section titled “Full review-and-merge cycle”

Review the changes and run the relevant tests before requesting approval to merge. For unattended merge logic, use the CI checks recipe.

Terminal window
bb pr checkout 42
bb pr diff 42
# After the user authorizes approval and merge:
bb pr approve 42
bb pr merge 42 --strategy squash --close-source-branch

Work an open review thread

Section titled “Work an open review thread”

Read unresolved threads, fix the code, then post and resolve only when authorized:

Terminal window
bb pr comments list 45 --all --unresolved
bb pr comments reply 45 109820 "Capped retries at 3 attempts in a1b2c3d."
bb pr comments resolve 45 109820

For multi-line markdown, pass the text on stdin with -F - and a quoted heredoc, so backticks and $ reach Bitbucket as written. The same flag works on bb pr create, bb pr edit and bb pr comments add:

Terminal window
bb pr comments reply 45 109820 -F - <<'EOF'
Capped retries at 3 attempts in `a1b2c3d`.
EOF

Draft PR workflow

Section titled “Draft PR workflow”
Terminal window
bb pr create -t "WIP: New dashboard" --draft
bb pr ready 48
bb pr reviewers add 48 '{alice-uuid}'

Security

Section titled “Security”

Normal bb commands use stored credentials internally, so the assistant does not need a token in its prompt. This is not a security boundary: an agent with file or shell access can read the config (plaintext unless credentialStorage is keychain) or run bb auth token. Use your assistant’s tool permissions to control that access. Rule and skill files provide instructions, not credential isolation.

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

Terminal window
export BB_USERNAME="[email protected]"
export BB_API_TOKEN="your-api-token"
bb auth login   # BB_USERNAME contains your Atlassian account email

Required API token scopes

Section titled “Required API token scopes”

Choose scopes for the operations your agent needs, using the command-to-scope reference. Read-only access still requires the appropriate read scope for each resource.

OAuth agents

Section titled “OAuth agents”

The CLI requests account repository repository:admin pullrequest pullrequest:write. The OAuth consumer’s configured scopes determine the resulting grant; this request does not narrow a consumer configured with more scopes.

For commands outside repository and PR work, use an API token with the required scopes or configure a custom consumer with those scopes. See Authentication and Atlassian’s OAuth scope rules.

Troubleshooting

Section titled “Troubleshooting”
Issue Solution
“Not authenticated” Run bb auth login; for tokens, set BB_USERNAME to your account email and BB_API_TOKEN before login
“Browser login needs an interactive terminal” The agent has no terminal, so OAuth can’t finish. Set BB_USERNAME and BB_API_TOKEN, or run bb auth login yourself
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. The npm package requires Bun 1.1.30+; standalone binaries need no runtime
AI using wrong flags Tell the AI to run bb <command> --help first
Windsurf not picking up rules Ensure the shared instructions are in the root AGENTS.md

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 of every page with a one-line description, plus the sets below
/<page>.md Any single page as markdown: add .md to its path, e.g. /commands/pr.md
/_llms-txt/pull-requests.txt Topic set: every pr page plus the reviewer and auto-merge recipes
/_llms-txt/pipelines-and-ci.txt Topic set: pipelines, deployments, commit statuses and CI/CD setup
/_llms-txt/scripting.txt Topic set: JSON output, error codes, environment variables and scripting
/llms-full.txt Every doc page concatenated as markdown
/llms-small.txt Abridged subset (excludes Help / FAQ / Changelog) for tight context windows

Start an agent at /llms.txt so it fetches only the pages it needs. All of these are generated at build time, so they always match the live docs. Give your assistant one of these URLs when it needs the reference. Automatic discovery depends on the assistant; publishing the files does not guarantee that it will fetch them.

Section titled “Related guides”