Environment Variables

Environment variables allow you to configure the CLI without storing credentials in files. This is especially useful for CI/CD pipelines and automation scripts.

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 and git context still win.	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. Equivalent to the global --no-unicode flag.	1
NO_COLOR	Disable color output globally when set to any value	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

Internal / System Variables

These variables are read by the CLI but are normally set by the runtime, your shell, or your operating system rather than by you. They are documented here 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.

Configuration Priority

Repository context is resolved in this order (highest priority first):

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

Authentication credentials are resolved from:

1. Configuration file (~/.config/bb/config.json on macOS/Linux, %APPDATA%\bb\config.json on Windows)
2. Environment variables (BB_USERNAME, BB_API_TOKEN) when running bb auth login — setting BB_API_TOKEN automatically uses API token auth instead of OAuth

For color output, precedence is:

1. --color (force color on — only available on bb pr diff, not a global flag)
2. FORCE_COLOR
3. --no-color (global flag, available on all commands)
4. NO_COLOR

---

Authentication with Environment Variables

Login from Environment Variables

When environment variables are set, bb auth login uses them automatically:

export BB_USERNAME=myuser
export BB_API_TOKEN=ATBB_your_token_here

bb auth login  # Uses env vars, no prompts

Non-Interactive Usage

For scripts and CI/CD, set both variables before running commands:

export BB_USERNAME=myuser
export BB_API_TOKEN=ATBB_your_token_here

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

Security Warning

Never commit environment variables containing tokens to version control. Use your CI/CD platform’s secrets management instead.

---

Shell Configuration

Bash

Add to ~/.bashrc or ~/.bash_profile:

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

Then reload:

source ~/.bashrc

Zsh

Add to ~/.zshrc:

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

Then reload:

source ~/.zshrc

Fish

Add to ~/.config/fish/config.fish:

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

Then reload:

source ~/.config/fish/config.fish

PowerShell

Add to your PowerShell profile ($PROFILE):

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

---

Temporary Session

Set variables for a single terminal session:

# Linux/macOS
export BB_USERNAME=myuser
export BB_API_TOKEN=ATBB_token

# Windows Command Prompt
set BB_USERNAME=myuser
set BB_API_TOKEN=ATBB_token

# Windows PowerShell
$env:BB_USERNAME = "myuser"
$env:BB_API_TOKEN = "ATBB_token"

Or inline with a single command:

BB_USERNAME=myuser BB_API_TOKEN=ATBB_token bb auth login && bb pr list -w workspace -r repo

---

Docker Usage

Pass environment variables to containers:

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 repo"

Or use 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 repo"

---

CI/CD Examples

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 }}
        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
  script:
    - npm 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:
          - npm install -g @pilatos/bitbucket-cli
          - bb auth login
          - bb pr list -w $BITBUCKET_WORKSPACE -r $BITBUCKET_REPO_SLUG --json

Tip

In Bitbucket Pipelines, BITBUCKET_WORKSPACE and BITBUCKET_REPO_SLUG are automatically available.

---

Security Best Practices

1. Never commit tokens to git

   • Add .env* to your .gitignore
   • Use CI/CD secrets management

2. Use minimal token scopes

   • Only grant permissions your script needs
   • Read-only tokens for read-only operations

3. Rotate tokens regularly

   • Especially after team member departures
   • Use short-lived tokens when possible

4. Use secrets managers in production

   • HashiCorp Vault
   • AWS Secrets Manager
   • Azure Key Vault

5. Audit token usage

   • Review which tokens are active
   • Revoke unused tokens