Skip to content
Bitbucket CLI Bitbucket CLI

AI Agent Integration

AI coding assistants can use the Bitbucket CLI to manage pull requests and repositories through natural conversation. Simply ask “Create a PR for this branch” and the AI handles the rest.

Benefits

Section titled “Benefits”
  • Natural language - No need to memorize command flags
  • Intelligent chaining - AI chains commands automatically
  • Team consistency - Encode conventions for everyone
  • Faster workflows - “Approve and merge PR 42” in one sentence

Setup

Section titled “Setup”

Choose your AI agent:

  1. Create the skill directory:

    Terminal window
    mkdir -p .claude/skills/bb-cli

  2. Create the skill file at .claude/skills/bb-cli/SKILL.md:

    ---
    name: bb-cli
    description: Execute Bitbucket Cloud CLI commands using `bb`. Use when creating, listing, editing, or managing pull requests, repositories, authentication, or configuration.
    allowed-tools: Bash(bb:*), Read, Grep, Glob
    ---
    

    # Bitbucket CLI (`bb`)
    

    Command-line interface for Bitbucket Cloud (@pilatos/bitbucket-cli).
    

    ## Quick Start
    

    ```bash
    bb auth status        # Check authentication
    bb pr list            # List open PRs
    bb pr create -t "..." # Create PR from current branch
    ```
    

     ## Requirements
    

     - Bun runtime 1.0+ installed (https://bun.sh)
     - `npm install -g @pilatos/bitbucket-cli` (or bun/pnpm)
     - Authenticated via `bb auth login` (env vars supported during login)
     - Run from git repo with Bitbucket remote
    

    ## Commands
    

    See the full command reference in the skill file or run `bb --help`.
    

    **Key commands:**
    - `bb pr create/list/view/diff/checkout/approve/merge/decline/ready/comments`
    - `bb repo clone/create/list/view/delete`
    - `bb auth login/logout/status/token`
    - `bb config get/set/list`
    

    ## Workflows
    

    **Create PR:**
    ```bash
    git add . && git commit -m "feat: description"
    git push -u origin feature-branch
    bb pr create -t "feat: description" -b "Details"
    ```
    

    **Review and Merge:**
    ```bash
    bb pr checkout 42
    bb pr diff 42
    bb pr approve 42
    bb pr merge 42 --strategy squash --close-source-branch
    ```
    

    **Draft PR:**
    ```bash
    bb pr create -t "WIP" --draft
    bb pr ready 42  # Mark as ready later
    ```
    

    ## Tips
    

    - Context auto-detection: run from git repo with Bitbucket remote
    - JSON output: all commands support `--json`
    - Error codes: 0=success, 1xxx=auth, 2xxx=API, 3xxx=git, 4xxx=config, 5xxx=validation, 6xxx=context, 7xxx=network

  3. Restart Claude Code to load the skill

  4. Test it: Ask “List open PRs in this repo”

Example Conversations

Section titled “Example Conversations”

Creating a PR:

You: Create a PR for my current branch titled "Add user validation"
AI: [Runs: bb pr create -t "Add user validation"]
    ✅ Created PR #42
    https://bitbucket.org/workspace/repo/pull-requests/42

Checking Open PRs:

You: What PRs need my review?
AI: [Runs: bb pr list --json]
    Found 3 open PRs:
    • #42 - Add user validation (by john, 2 hours ago)
    • #41 - Fix login bug (by jane, 1 day ago)
    • #40 - Update dependencies (by bot, 3 days ago)

Review Workflow:

You: Review PR 42 and approve it if it looks good
AI: [Runs: bb pr view 42, bb pr diff 42]
    Changes look good. Approving...
    [Runs: bb pr approve 42]
    ✅ Approved PR #42.

Draft PRs:

You: Create a draft PR for my WIP
AI: [Runs: bb pr create -t "WIP: Feature" --draft]
    ✅ Created draft PR #43


You: Mark it ready for review
AI: [Runs: bb pr ready 43]
    ✅ Marked PR #43 as ready for review

Team Conventions

Section titled “Team Conventions”

Add team-specific rules to your AI instructions:

### Branch Naming
- Features: `feat/<ticket>-<description>`
- Bugs: `fix/<ticket>-<description>`
- Hotfixes: `hotfix/<description>`


### PR Requirements
- All PRs need one approval
- Use draft PRs for work-in-progress
- Always squash merge features: `--strategy squash`
- Always delete source branches: `--close-source-branch`


### Review Process
1. bb pr checkout <id>
2. Review changes with bb pr diff <id>
3. bb pr approve <id>
4. bb pr merge <id> --strategy squash --close-source-branch

This ensures everyone follows the same workflow automatically.

Security

Section titled “Security”
Terminal window
export BB_USERNAME=your-username
export BB_API_TOKEN=your-api-token

For Claude Code, limit permissions in the skill:

allowed-tools: Bash(bb:*), Read, Grep, Glob  # Good - only bb commands

Troubleshooting

Section titled “Troubleshooting”
IssueSolution
”Not authenticated”Set BB_USERNAME and BB_API_TOKEN, then run bb auth login
Commands still promptingClaude Code: check allowed-tools includes Bash(bb:*)
”Could not determine repo”Run from git repo with Bitbucket remote, or use -w/-r flags
AI using wrong syntaxAdd more examples to your skill/instructions
opencode not finding commandsEnsure bb CLI is installed and in PATH
Section titled “Related Guides”