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, snippets, workspaces and projects, browsing, configuration, and shell completion. Anything without a typed command — branch permissions, webhooks — 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)
Commits & build statuses - bb commit list/view, bb status list/set
Workspaces & projects - bb workspace list/view, bb project list/view/create
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
Raw API access - bb api passthrough to any Bitbucket Cloud 2.0 endpoint

No typed command yet — use bb api:

Branch permissions
Webhooks

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, app passwords are deprecated. Atlassian no longer allows creating new app passwords, and existing ones are being phased out — see the official deprecation notice for current timelines.

Use OAuth (recommended) or API tokens instead:

# OAuth (recommended — opens browser)
bb auth login

# API token
bb auth login -u your-username -p your-api-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=account-a
export BB_API_TOKEN=token-a
bb auth login

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

Each login overwrites the credentials in the config file, so parallel shells cannot hold different accounts.

What scopes does my token need?

OAuth login requests one fixed set: account, repository, repository:admin, pullrequest, pullrequest:write. You cannot change it. That covers auth, repositories, and pull requests, but not bb repo delete, bb pipeline *, bb snippet *, or bb project * — for those, log in with an API token carrying the scopes below.

API token scopes:

Scope	Required for
`read:user:bitbucket`	`bb auth status`, plus the user lookups in `bb pr list --mine`, `bb pr create --reviewer`, and `bb pr reviewers add/remove`
`read:repository:bitbucket`	`bb repo list`, `bb repo view`, `bb commit list/view`, `bb status list`
`write:repository:bitbucket`	`bb status set`
`admin:repository:bitbucket`	`bb repo create`, `bb repo default-reviewers add/remove`
`delete:repository:bitbucket`	`bb repo delete`
`read:pullrequest:bitbucket`	`bb pr list`, `bb pr view`, `bb repo default-reviewers list`, all `bb pr comments` subcommands
`write:pullrequest:bitbucket`	`bb pr create`, `bb pr edit`, `bb pr merge`, `bb pr approve`, `bb pr decline`, `bb pr ready`, `bb pr reviewers add/remove`
`read:pipeline:bitbucket`	`bb pipeline list/view/logs`
`write:pipeline:bitbucket`	`bb pipeline run`, `bb pipeline stop`
`read:snippet:bitbucket`	`bb snippet list`, `bb snippet view`, all `bb snippet comments` subcommands
`write:snippet:bitbucket`	`bb snippet create/edit/watch/unwatch`
`delete:snippet:bitbucket`	`bb snippet delete`
`read:project:bitbucket`	`bb project list`, `bb project view`
`admin:project:bitbucket`	`bb project create`
`read:workspace:bitbucket`	`bb workspace list`, `bb workspace view`

See Token Scopes for the per-command breakdown.

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?

Only bb completion install, which asks which shell you use. Every other command takes flags and arguments.

bb auth login is browser-interactive but never prompts in the terminal — it opens your browser and waits up to 5 minutes for the callback on http://localhost:19872/callback.

Destructive commands don’t prompt either. Without -y/--yes they fail with Use --yes to confirm.:

bb repo delete myworkspace/old-repo --yes

That gate applies to bb repo delete, bb repo default-reviewers remove, bb pr comments delete, bb snippet delete, and bb snippet comments delete.

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 — those two variables are read only at login time, so every job needs the login step before any other command

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 --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'

List commands return 25 items by default. Pass --limit <n> for a different cap, or --all to fetch every page (--all overrides --limit).

Can I use bb with git hooks?

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

#!/bin/bash
branch=$(git branch --show-current)
prs=$(bb pr list --json --jq "[.pullRequests[] | select(.source.branch.name == \"$branch\")] | length" 2>/dev/null)

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

The branch name is interpolated by the shell, not read from the environment: the embedded jq runs in a sandbox where env and $ENV do not see your shell variables.

Contributing

How can I contribute?

See CONTRIBUTING.md for:

Development setup
Code style guidelines
Pull request process
Changeset requirements

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