bitbucket-setup

Bitbucket CLI (bbt) Setup

Help the user install and configure the bbt Bitbucket CLI tool.

Installation

1. First check if bbt is already installed:

   bbt --version
   

2. If not installed, run the install script:

   ${CLAUDE_PLUGIN_ROOT}/scripts/install-bbt.sh
   

3. If the script is not available, install manually based on the platform:

   • macOS / Linux (Homebrew):

     brew tap romaintb/bbt https://codeberg.org/romaintb/homebrew-bbt.git
     brew install bbt
     

   • Arch Linux (AUR):

     yay -S bbt
     

   • Go (any platform with Go installed):

     go install codeberg.org/romaintb/bbt@latest
     

     Then ensure $(go env GOPATH)/bin is in your PATH.

Authentication

After installation, help the user authenticate with Bitbucket Cloud:

1. Interactive login:

   bbt auth login
   

   This will prompt for your Bitbucket workspace and an app password or personal access token (PAT).

2. Verify authentication:

   bbt auth status
   

Generating a Bitbucket App Password

To create an app password for authentication:

1. Go to Bitbucket Cloud → Personal Settings → App passwords
2. Click Create app password
3. Grant these permissions: Repositories (Read/Write), Pull requests (Read/Write), Issues (Read/Write), Pipelines (Read/Write)
4. Copy the generated password — it will only be shown once

Configuration

bbt stores its configuration in ~/.config/bbt/config.yaml. When inside a git repository with a Bitbucket remote, bbt auto-detects the workspace and repository — no need to specify -R workspace/repo for most commands.

Troubleshooting

• If bbt is not found after Go install, ensure $(go env GOPATH)/bin is in your PATH:

  export PATH="$(go env GOPATH)/bin:$PATH"
  

• For Homebrew on Linux, ensure Homebrew itself is installed first: https://brew.sh
• Check authentication issues with bbt auth status