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 Atlassian account email (fallback for API-token bb auth login)	[email protected]
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_ACCOUNT	Saved account to use for this invocation, instead of the active one. --account wins. See Multiple accounts.	work
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
BB_PROMPT_DISABLED	When set to any non-empty value, never prompt, even in an interactive terminal (bb completion install still asks for your shell). Same effect as the global --no-input flag. See --no-input.	1
BB_DETAILED_EXIT_CODES	When set to any non-empty value, exit with a status per failure class: 2 usage, 3 not found, 4 authentication, 5 confirmation required (otherwise every failure exits 1). See Exit codes.	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
BB_PAGER	Pager for bb pr diff, bb pr view and bb pipeline logs on a terminal. Overrides PAGER; defaults to less -FRX. Empty or cat turns paging off. Split on whitespace, no shell quoting. See Pager.	less -R
PAGER	Fallback pager when BB_PAGER is unset.	less
LESS	Options for less. Set to FRX for the pager when you have not set it, so PAGER=less still shows colors.	-FRX
BB_DEBUG	HTTP debug tracing on stderr. http logs method, URL, status (or network error code) and elapsed time for every API call; verbose also logs the request and response bodies, secrets redacted. 0, false, off, no or none disables it, even when DEBUG=true is set; any other non-empty value (e.g. 1) means http. Any level also prints the browser-open and version-check diagnostics on stderr. See HTTP debug tracing.	http
DEBUG	Alias for BB_DEBUG=verbose. Must equal the literal string true, and is ignored when BB_DEBUG is set.	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. bb repo downloads upload adds transfer time for the upload size on top.	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; it affects API requests, not git clone. A stalled request can then wait indefinitely.

Pager

On a terminal, bb pr diff, bb pr view and bb pipeline logs open their output in a pager. The default less -FRX quits right away when the output fits on one screen (-F), keeps colors (-R) and leaves the text on screen after you quit (-X). Ctrl+C goes to the pager while it is open. There is no pager with --json or when stdout is piped. If the pager can’t be started (for example no less on Windows) or exits with an error, the output is printed directly. A command that fails prints what it has so far without the pager.

BB_PAGER= bb pr diff 42        # no pager for this run
export BB_PAGER="less -RS"     # don't wrap long diff lines

HTTP debug tracing

BB_DEBUG=http prints one line when a request is sent and one when it finishes. Each line starts with [HTTP] and a six-character correlation id, so lines from overlapping requests can be matched up:

$ BB_DEBUG=http bb pr list
[HTTP] 3f9a1c GET https://api.bitbucket.org/2.0/repositories/my-ws/my-repo/pullrequests?[redacted]
[HTTP] 3f9a1c 200 GET https://api.bitbucket.org/2.0/repositories/my-ws/my-repo/pullrequests?[redacted] 184ms

A retried request (rate limit, 502/503/504, transient network error) or an OAuth token refresh keeps its id, and the resent line ends in (attempt N). The elapsed time on an outcome line covers one attempt on the wire. Time spent before sending is shown separately so slow runs can be explained:

• (waited Nms) on a request line: how long it was held back, by rate-limit pacing for a first attempt, or since the previous attempt finished (retry backoff, token refresh) for a retry.
• (auth Nms) on an outcome line: credential lookup, including a proactive OAuth token refresh, between the request line and the send.

A request that gets no response logs the network error code instead of a status, e.g. ECONNRESET or ECONNABORTED for a timeout. A failure before the request is sent (e.g. missing credentials) logs [HTTP] Error: <message> right after its request line.

BB_DEBUG=verbose adds a Request Body: line after a request line that has a body, and a Response Body: (or Error Response Body:) line after each outcome. Query strings are always replaced with ?[redacted], and values under keys such as access_token, password and authorization are replaced with [REDACTED] in JSON bodies. Headers are never logged.

Trace lines go to stderr, including with --json. JSON output stays on stdout, so it can be piped into another tool while tracing is enabled.

POSIX locale variables

If neither --locale nor BB_LOCALE is set, the CLI reads the standard POSIX locale variables in the order LC_TIME, 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.
BB_COMPLETION_SHELL	The completion scripts	Set by the scripts from bb completion <shell> to bash, zsh, fish or powershell, so candidates come back in that shell’s format. Scripts written by older versions don’t set it, and $SHELL decides instead. Don’t 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 stored username (your Atlassian account email) and API 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=[email protected]
export BB_API_TOKEN=ATBB_your_token_here

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

Or inline, without exporting:

BB_USERNAME=[email protected] BB_API_TOKEN=ATBB_token bb auth login

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

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

Shell configuration

Set [email protected] in your shell profile if you want an email fallback. Load BB_API_TOKEN from a secret store when logging in; avoid putting it in your shell profile. These variables select credentials for login, not for subsequent API calls.

Docker

Pass credentials from a secret store and run bb auth login inside the container before API commands. The npm package still needs Bun on PATH. Config credentials are stored on disk; account for that when mounting a home directory or building an image.

CI/CD examples

See CI/CD Integration for runner setup and authentication. Use an Atlassian account email for BB_USERNAME, and store BB_API_TOKEN in the runner’s secret store.

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.