FAQ - Frequently Asked Questions About Bitbucket CLI

General

Is this an official Atlassian/Bitbucket tool?

No. This is an unofficial, community-maintained CLI tool. It is not affiliated with or endorsed by Atlassian or Bitbucket. The project is open source and maintained by volunteers.

How does this compare to GitHub CLI (gh)?

bb follows gh’s command shapes for Bitbucket Cloud. It covers authentication, repositories, pull requests, pipelines, commits and build statuses, deployments, branch restrictions, SSH and GPG keys, snippets, workspaces and projects, code search, webhooks, browsing, configuration, and shell completion. Anything without a typed command, such as deploy keys, is reachable through bb api, the analog of gh api.

What Bitbucket features are supported?

Authentication - Login, logout, status, token display
Repositories - Clone, create, list, view, delete, default reviewers (list/add/remove)
Pull requests - Create (with optional default-reviewer attachment), list, view, edit, merge, approve, decline, ready (mark draft ready), checkout, diff, activity log, CI/CD checks, comments (list/add/edit/delete/view/reply/resolve/unresolve, with --resolved/--unresolved filters on list), reviewers (list/add/remove)
Pipelines - List, view, run (with --var key=value), stop, logs (--step)
Deployments - bb deployment list/view/environments
Branch restrictions - bb branch-restriction list/view/create/delete
SSH & GPG keys - bb ssh-key list/add/delete, bb gpg-key list/add/delete (your own account)
Commits & build statuses - bb commit list/view, bb status list/set
Workspaces & projects - bb workspace list/view, bb project list/view/create
Code search - bb search code across a workspace or one repository
Webhooks - bb webhook list/view/create/delete for repositories and workspaces
Snippets - List, view (with file contents), create, edit (metadata or file upload), delete, watch/unwatch, comments (list/add/edit/delete)
Browse - Open repository pages, PRs, files, commits, and pipelines in the browser
Configuration - Get, set, list settings
Shell completion - Bash, Zsh, Fish, PowerShell
Raw API access - bb api passthrough to any Bitbucket Cloud 2.0 endpoint

Use bb api for other endpoints, such as deploy keys. Run bb --help for the current command groups.

Does this work with Bitbucket Server/Data Center?

No. The CLI supports Bitbucket Cloud only. Bitbucket Server (self-hosted) uses a different API.

If you need Bitbucket Server support, open an issue.

Authentication

Where are my credentials stored?

Credentials are stored in a local configuration file:

Platform	Location
macOS/Linux	`~/.config/bb/config.json`
Windows	`%APPDATA%\bb\config.json`

The file is created with restricted permissions (owner read/write only on Unix systems).

Can I use app passwords?

No. Atlassian disabled all Bitbucket app passwords on July 28, 2026 (see the deprecation notice).

Use OAuth (recommended) or API tokens instead:

# OAuth (recommended, opens browser)
bb auth login

# API token
printf '%s' "$BB_API_TOKEN" | bb auth login -u [email protected] --with-token

How do I use multiple Bitbucket accounts?

One config file, one active account. Switch by logging in again:

# Switch to account A
export BB_USERNAME=[email protected]
export BB_API_TOKEN=token-a
bb auth login

# Later, switch to account B
export BB_USERNAME=[email protected]
export BB_API_TOKEN=token-b
bb auth login

Each login overwrites the credentials in the shared config file. Environment variables are read at login time; changing them does not isolate accounts in parallel shells.

What scopes does my token need?

Use the token scope reference to select the API-token scopes for your commands. For API-token authentication, BB_USERNAME and -u contain your Atlassian account email, not your Bitbucket username.

OAuth grants depend on the consumer’s configured scopes. The CLI’s requested scope list does not limit a custom consumer to that list. See Authentication and Atlassian’s OAuth documentation.

Commands

How do I avoid typing workspace/repo every time?

Don’t know your workspace slug? Run bb workspace list.

Option 1: Set a default

bb config set defaultWorkspace myworkspace

Option 2: Work from a cloned repository

cd /path/to/myrepo
bb pr list  # workspace and repo come from the git remote

Option 3: Export BB_WORKSPACE for a shell session

export BB_WORKSPACE=myworkspace

Precedence: -w/--workspace beats the git remote, which beats BB_WORKSPACE, which beats defaultWorkspace.

See Repository Context for details.

Does bb support interactive mode?

Partly. Every command is driven by flags and arguments, and a few of them ask for what is missing when you run them in an interactive terminal:

Destructive commands (bb repo delete, bb repo default-reviewers remove, bb repo downloads delete, bb pr comments delete, bb snippet delete, bb snippet comments delete, bb webhook delete, bb branch-restriction delete, bb ssh-key delete, bb gpg-key delete) ask Continue? (y/N) when -y/--yes is missing.
bb pr create asks for the title (and an optional description) when --title is missing.
bb auth login asks whether to use the browser or an API token, and for a missing account email or token.

Scripts and CI are unaffected. Prompts need stdin and stdout to both be terminals, and --json, --no-input or BB_PROMPT_DISABLED=1 turn them off.

bb completion install is the exception: it always asks which shell you use, even with these switches, so don’t run it in a script. See bb completion install.

Without prompts a destructive command fails with Use --yes to confirm., so pass the flag:

bb repo delete myworkspace/old-repo --yes

See --no-input for the details.

Can I create a PR from uncommitted changes?

No. You must:

Commit your changes
Push to a remote branch
Then create the PR

git add .
git commit -m "My changes"
git push -u origin my-branch
bb pr create -t "My PR"

How do I see what’s in a PR before checking it out?

Use bb pr diff:

# View changes
bb pr diff 42

# Just see changed files
bb pr diff 42 --name-only

# See statistics
bb pr diff 42 --stat

Integration

Can I use bb in CI/CD pipelines?

Yes. See the CI/CD Integration Guide for complete examples.

Quick setup:

Store credentials as CI/CD secrets
Set BB_USERNAME and BB_API_TOKEN
Install the CLI and run bb auth login. These variables are read at login time, so each fresh job needs the login step before other commands.

How do I pipe output to other commands?

--json emits machine-readable JSON. --jq <expression> filters it with an embedded jq, so no external jq binary is needed and it behaves the same on Windows.

# PR titles
bb pr list --json --jq '.pullRequests[].title'

# PR count
bb pr list --all --json --jq '.count'

# Filter by author
bb pr list --json --jq '.pullRequests[] | select((.author.nickname // .author.display_name) == "alice")'

--jq requires --json. Field projection runs before jq and drops the envelope, so --json id,title hands jq a bare array:

bb pr list --json id,title --jq '.[] | .title'

Paginated list commands generally return 25 items by default. For commands that support them, --limit <n> changes the cap and --all fetches every page. See list-command flags.

Can I use bb with git hooks?

Yes. Example pre-push hook that warns when a PR already exists:

This hook uses an external jq so the branch name can be passed as data without shell interpolation into the filter:

#!/bin/bash
set -euo pipefail

branch=$(git branch --show-current)
if [ -z "$branch" ]; then
  exit 0
fi

if ! prs=$(bb pr list --all --json | \
  jq --arg branch "$branch" '[.pullRequests[] | select(.source.branch.name == $branch)] | length'); then
  echo "Could not check for an existing PR" >&2
  exit 1
fi

if [ "$prs" -gt 0 ]; then
  echo "Note: PR already exists for branch $branch"
fi

--all includes PRs beyond the first page. The hook checks the current local branch; it does not inspect every ref in a multi-ref push.

Contributing

How can I contribute?

See CONTRIBUTING.md for:

Development setup
Pull request process
Changeset requirements

Code conventions, including the rules AI coding agents follow, live in AGENTS.md.

How do I report bugs?

Check existing issues
If not already reported, open a new issue
Include:
- CLI version (bb --version)
- Operating system
- Complete error message
- Steps to reproduce

How do I request features?

Open an issue with:

Clear description of the feature
Use case / why it’s needed
Examples of how it would work

Update notifications

How do I disable update notifications?

bb config set skipVersionCheck true

The CLI checks for a newer published version after every command, then prints a one-time banner to stderr. The banner is suppressed in --json mode, when stderr is not a TTY, and in CI.

How often does the CLI check for updates?

By default, the CLI checks once per day (24 hours). You can change this interval:

# Check weekly
bb config set versionCheckInterval 7

# Check every 3 days
bb config set versionCheckInterval 3

The value is in days.

versionCheckInterval must be a positive integer (>= 1). skipVersionCheck only accepts true or false.

Both settings are stored as typed JSON values, so JSON output returns:

{ "key": "skipVersionCheck", "value": true }

Will update checks slow down the CLI?

No. The check is:

Performed after the command’s own output, on stderr
Cached for 24 hours (or your configured interval)
Skipped entirely in CI environments
Suppressed in --json mode and when stderr is not a TTY, so piped output stays clean
Swallowed silently when the npm registry is unreachable

Does the CLI auto-update?

No. The CLI only notifies you that an update is available. You must manually update:

bun install -g @pilatos/bitbucket-cli