Environment Variables

Every environment variable the CLI reads. bb --help lists the main ones in its footer.

Available variables

Variable	Description	Example
BB_USERNAME	Your Bitbucket username (fallback for bb auth login)	myuser
BB_API_TOKEN	Your Bitbucket API token (fallback for bb auth login; forces API token auth when set)	ATBB...
BB_WORKSPACE	Default workspace. Overrides config.defaultWorkspace. --workspace always wins; the git remote wins too, but only on repository-scoped commands — see Resolution order.	myworkspace
BB_LOCALE	BCP-47 locale tag for date/time formatting. --locale takes precedence; falls back to LC_TIME/LC_ALL/LANG, then en-US.	de-DE
BB_NO_UNICODE	When set to any non-empty value, use ASCII fallbacks for separators, arrows, and status icons. Same effect as the global --no-unicode flag, but it cannot be overridden per command: --unicode is accepted and does nothing while this is set. Unset the variable instead.	1
NO_COLOR	Disable color output globally. Triggers on any value, including the empty string.	1
FORCE_COLOR	Force-enable color output globally (any value except 0)	1
DEBUG	Enable HTTP debug logging (request method, URL, status, response body for every API call). Must equal the literal string true.	true
BB_HTTP_TIMEOUT	Per-request HTTP timeout in milliseconds for Bitbucket API calls. Prevents the CLI from hanging forever when a server accepts a connection but never responds. Defaults to 30000 (30s). Set to 0 to disable the timeout entirely. Invalid or negative values fall back to the default. A timed-out request is reported as a network error.	60000
BB_API_BASE_URL	Base URL for Bitbucket API calls. Defaults to https://api.bitbucket.org/2.0. Point it at a gateway, a mirror, or a local mock server (trailing slashes are stripped).	http://localhost:8080/2.0

BB_HTTP_TIMEOUT is in milliseconds

BB_HTTP_TIMEOUT=60 means 60 milliseconds, so almost every request fails. For a 60-second ceiling use BB_HTTP_TIMEOUT=60000. In CI, set something short like BB_HTTP_TIMEOUT=15000 so a stalled call fails fast instead of hanging the pipeline. BB_HTTP_TIMEOUT=0 disables the timeout — useful for very large clones or exports, but a hung request in CI has no human to Ctrl-C.

POSIX locale variables

If neither --locale nor BB_LOCALE is set, the CLI reads the standard POSIX locale variables — LC_TIME, then LC_ALL, then LANG — and falls back to en-US if none is usable. LC_TIME is deliberately checked before LC_ALL, which is the reverse of the usual POSIX override order, so setting both means LC_TIME wins.

Values are normalised before use: a .UTF-8 codeset suffix and an @euro-style modifier are stripped, _ becomes - (de_DE.UTF-8 → de-DE), and the C and POSIX locales map to en-US. Unset them, or pass --locale, to pin formatting explicitly.

CI detection

The update check is skipped when any of these is set to any value:

CI, CONTINUOUS_INTEGRATION, BUILD_ID, BUILD_NUMBER, DRONE, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, TRAVIS, JENKINS_URL, HUDSON_URL

Set CI=1 to get the same behavior locally.

Internal / system variables

Set by the runtime, your shell, or your operating system rather than by you. Documented so they aren’t surprising during troubleshooting.

Variable	Set by	Description
NODE_ENV	Test runners	When set to test, the CLI suppresses process.exitCode = 1 on errors so a single failing test cannot cascade into later tests. Don’t set this in production.
COMP_LINE	tabtab / your shell	Set automatically while shell completion is being computed (bb completion). Its presence triggers the completion path; you should not set it manually.
APPDATA	Windows	Used to locate the config file at %APPDATA%\bb\config.json on Windows. The CLI falls back to %USERPROFILE%\AppData\Roaming\bb\config.json if it isn’t set.

Resolution order

Workspace and repository, highest priority first:

1. Command-line flags (--workspace, --repo)
2. Git repository context (detected from the remote URL)
3. BB_WORKSPACE (workspace only)
4. Configuration file (defaultWorkspace, workspace only)

Step 2 does not apply to workspace-only commands — bb workspace view, every bb project and bb snippet command, bb repo list, bb repo create, bb repo clone, and bb api filling a {workspace} placeholder go straight from the flag to BB_WORKSPACE to defaultWorkspace.

Color, highest priority first. The default with none of them set is colors on:

1. --color — matched by a raw scan of argv, so bb pr diff 42 --color never still turns global color on
2. FORCE_COLOR (any value except 0)
3. --no-color
4. NO_COLOR (any value, including the empty string)

Credentials are not a chain. bb pr list and every other API call read the username and token from the config file only; if nothing is stored there the command fails with error 1001 even when BB_USERNAME and BB_API_TOKEN are exported. Those two variables are read by bb auth login and nowhere else — run it once and it writes the config file.

Inside bb auth login:

• --username / -u beats BB_USERNAME.
• --with-token (token on stdin) beats --password / -p, which beats BB_API_TOKEN. Combining --with-token with --password is an error.
• Setting BB_API_TOKEN at all selects API token auth instead of OAuth.

Authentication with environment variables

bb auth login picks up both variables, so it runs without prompts:

export BB_USERNAME=myuser
export BB_API_TOKEN=ATBB_your_token_here

bb auth login
bb pr list -w myworkspace -r myrepo

Or inline, without exporting:

BB_USERNAME=myuser BB_API_TOKEN=ATBB_token bb auth login

To keep the token out of shell history and ps output, pipe it instead:

echo "$BB_API_TOKEN" | bb auth login -u myuser --with-token

Shell configuration

Add to your shell’s startup file, then reload it or open a new terminal:

Bash

~/.bashrc or ~/.bash_profile:

export BB_USERNAME="your-username"
export BB_API_TOKEN="your-api-token"

Zsh

~/.zshrc:

export BB_USERNAME="your-username"
export BB_API_TOKEN="your-api-token"

Fish

~/.config/fish/config.fish:

set -gx BB_USERNAME "your-username"
set -gx BB_API_TOKEN "your-api-token"

PowerShell

Your profile ($PROFILE):

$env:BB_USERNAME = "your-username"
$env:BB_API_TOKEN = "your-api-token"

Docker

docker run -e BB_USERNAME=myuser \
           -e BB_API_TOKEN=ATBB_token \
           your-image sh -lc "bb auth login && bb pr list -w workspace -r myrepo"

Or an env file:

# .env.bb (not committed to git!)
BB_USERNAME=myuser
BB_API_TOKEN=ATBB_token

docker run --env-file .env.bb your-image sh -lc "bb auth login && bb pr list -w workspace -r myrepo"

CI/CD examples

The package is published to npm but runs on Bun — bb exits immediately under Node — so every runner needs Bun on PATH.

GitHub Actions

name: PR Status
on: [push]

jobs:
  check-prs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Install Bitbucket CLI
        run: npm install -g @pilatos/bitbucket-cli

      - name: List PRs
        env:
          BB_USERNAME: ${{ secrets.BB_USERNAME }}
          BB_API_TOKEN: ${{ secrets.BB_API_TOKEN }}
          BB_HTTP_TIMEOUT: 15000
        run: |
          bb auth login
          bb pr list -w myworkspace -r myrepo --json

GitLab CI

check-prs:
  image: oven/bun:latest
  variables:
    BB_USERNAME: $BB_USERNAME
    BB_API_TOKEN: $BB_API_TOKEN
    BB_HTTP_TIMEOUT: 15000
  script:
    - bun install -g @pilatos/bitbucket-cli
    - bb auth login
    - bb pr list -w myworkspace -r myrepo --json

Bitbucket Pipelines

image: oven/bun:latest

pipelines:
  default:
    - step:
        name: Check PRs
        script:
          - bun install -g @pilatos/bitbucket-cli
          - bb auth login
          - bb pr list -w $BITBUCKET_WORKSPACE -r $BITBUCKET_REPO_SLUG --json

BITBUCKET_WORKSPACE and BITBUCKET_REPO_SLUG are provided by Bitbucket Pipelines automatically.

Keeping tokens safe

• Add .env* to .gitignore and pass tokens through your CI platform’s secrets store. Never commit them.
• Grant the token only the scopes the script uses. See Token Scopes for the scope each command needs.