Skip to content
Bitbucket CLI

Authentication

The Bitbucket CLI uses API Tokens for authentication. This is a secure way to grant CLI access without exposing your main account password.

Create an API Token

  1. Log in to Bitbucket
  2. Go to Personal settings (click your avatar in the bottom left)
  3. Navigate to API tokens under “Access management”
  4. Click Create API token
  5. Give it a descriptive name (e.g., “Bitbucket CLI”)
  6. Select the required scopes:
    • Account: Read
    • Repositories: Read, Write, Admin (depending on your needs)
    • Pull requests: Read, Write
  7. Click Create
  8. Copy the generated token - you won’t be able to see it again!

Login

Terminal window
bb auth login -u your-username -p your-api-token

Using Environment Variables

You can also set credentials via environment variables, which is especially useful for CI/CD pipelines:

Terminal window
export BB_USERNAME=your-username
export BB_API_TOKEN=your-api-token
bb auth login

See Environment Variables Reference for more details on using environment variables in scripts and CI/CD.

Check Auth Status

Terminal window
bb auth status

This shows your current authentication status and account information.

Logout

Terminal window
bb auth logout

This removes stored credentials from your system.

Configuration Storage

Credentials are stored in:

  • Linux/macOS: ~/.config/bb/config.json
  • Windows: %APPDATA%\bb\config.json

See Configuration File Reference for details on the config file format.

Next Steps