Environment Variables¶

Every environment variable bb reads, what it does, and what happens when it is unset.

A flag wins over these variables, and they win over the configuration files. Configuration gives the whole order.

`.env` files¶

Before it resolves anything, bb reads .env files and puts what they hold into the environment for that one invocation. A variable the environment already carries is left alone, so exporting a value always wins over a file, and the values never reach any other process.

Which files are read depends on whether you are in a repository:

Where you are	Files read
Inside a repository, marked by a `.git` or a `go.mod`	`.env` in the working directory and in every parent up to and including that root
Anywhere else	`.env` in the working directory, and nothing above it

When two of them set the same variable, the nearest to the working directory wins. A .env is read for its content only; it is not configuration, and none of the bb configuration keys work in it. Write variable names, as they appear in the tables below:

BITBUCKET_PROJECT_KEY=PAY
BB_RETRY_COUNT=5

A .env sets only these variables, each written in capitals as here:

Kind	Variables
Credentials	`BITBUCKET_TOKEN`, `BITBUCKET_USERNAME`, `BITBUCKET_USER`, `BITBUCKET_PASSWORD`, `ADMIN_USER`, `ADMIN_PASSWORD`
Repository	`BITBUCKET_PROJECT_KEY`, `BITBUCKET_REPO_SLUG`, `BITBUCKET_VERSION_TARGET`
Waiting and retrying	`BB_REQUEST_TIMEOUT`, `BB_RETRY_COUNT`, `BB_RETRY_BACKOFF`
Webhook secrets	`BB_WEBHOOK_SECRET`, `BB_WEBHOOK_PASSWORD`
Output and prompts	`BB_LOG_LEVEL`, `BB_LOG_FORMAT`, `NO_COLOR`, `BB_NO_PROMPT`, `BB_NO_PROMPT_VARS`
Stricter only	`BB_REQUIRE_KEYRING`, `BB_DISABLE_UPDATE`

Nothing else in a .env reaches bb: not the host or BB_CONFIG_PATH, not TLS or proxy settings, and not the variables git and other programs read. bb warns once for each of its own settings a .env names and it leaves unset, naming the file, and talks to the host your environment or your own configuration file names. Other names, such as your application's, it passes over without a word.

A .env arrives with a clone

It is a file in a repository, so anyone who can open a pull request can add one, and it is read by the next bb command run in that checkout. It cannot choose the host or how bb reaches it, and a credential is released only for the host it was stored for, but a token in it makes bb act as that token's user. Read the .env in an unfamiliar repository before running bb in it.

bb update does not read .env. It resolves its own settings without going through the configuration layer, so BB_UPDATE_BASE_URL, BB_DISABLE_UPDATE and BB_ALLOW_HTTP_UPDATE are taken from the real environment, your own file and the system file, never from a .env or a workspace file. A repository cannot redirect where the next bb update fetches a binary from.

bb doctor shows which file every setting came from, naming the .env by path when that is where it was:

bb doctor

Connection¶

Variable	Default	Effect
`BITBUCKET_URL`	none	Base URL of the Bitbucket Data Center instance, including scheme and any context path — `https://bitbucket.example.com` or `https://example.com/bitbucket`.
`BITBUCKET_VERSION_TARGET`	unset	A Bitbucket version you record for your own environment. `bb auth status` shows it; nothing in `bb` acts on it, and `bb` reads the release from the server where a release differs.
`BB_REQUEST_TIMEOUT`	`20s`	Per-request HTTP timeout, as a Go duration (`45s`, `2m`). A download — `bb update`, `bb repo archive`, `bb repo cat`, `bb repo browse raw`, a `bb api` GET — takes as long as it needs: the timeout applies to each wait for the server, so it fails only when nothing arrives for that long. Equivalent flag: `--request-timeout`.
`BB_RETRY_COUNT`	`2`	Retry attempts for transient failures — connection errors, 429, 5xx. A download that breaks off resumes where it stopped if the server supports ranges, and otherwise starts over — except onto stdout, once bytes have gone out. `0` disables retrying. Equivalent flag: `--retry-count`.
`BB_RETRY_BACKOFF`	`250ms`	Base delay between retries, multiplied by the attempt number. A `Retry-After` header from the server wins over this. Equivalent flag: `--retry-backoff`.

Authentication¶

A token on the command line ends up in your shell history and in the process list, where other users on the machine can read it. BITBUCKET_TOKEN is the answer to that: it keeps the secret out of argv without storing anything on disk, which is what makes it the right choice for CI and containers.

Variable	Default	Effect
`BITBUCKET_TOKEN`	none	Personal access token, sent as a bearer token. Takes precedence over username/password.
`BITBUCKET_USERNAME`	none	Username for basic authentication. Falls back to `BITBUCKET_USER`, then `ADMIN_USER`.
`BITBUCKET_PASSWORD`	none	Password for basic authentication. Falls back to `ADMIN_PASSWORD`.
`BB_REQUIRE_KEYRING`	unset	`1` makes `bb` refuse to read or write credentials through the plaintext config fallback. Use it where storing a secret unencrypted is not acceptable — see keyring storage.
`BB_DISABLE_STORED_CONFIG`	unset	`1` reads neither the stored configuration file nor any stored credential. Workspace configuration (`.bb/config.yaml`) and system policy still apply. Useful in CI, where a stray config file on a shared runner would otherwise be picked up.
`BB_CONFIG_PATH`	`%AppData%\bb\config.yaml`, `~/Library/Application Support/bb/config.yaml` or `~/.config/bb/config.yaml`	Path to the stored configuration file. See Two identities on one host.
`BB_WORKSPACE_CONFIG_PATH`	unset	Path to the per-workspace configuration file. Unset, `bb` looks for `.bb/config.yaml`, searching upward from the working directory and stopping at the repository root.

BITBUCKET_USER, ADMIN_USER and ADMIN_PASSWORD exist because the test harness sets them. They work, but prefer the primary names.

TLS and proxies¶

Variable	Default	Effect
`BB_CA_FILE`	unset	Path to a PEM bundle of additional trusted CAs. Added to the system trust store, not a replacement for it. Equivalent flag: `--ca-file`.
`BB_CLIENT_CERT`	unset	Path to a PEM-encoded client certificate or certificate chain for mutual TLS (mTLS). Must be set together with `BB_CLIENT_KEY`. Equivalent flag: `--client-cert`.
`BB_CLIENT_KEY`	unset	Path to a PEM-encoded client private key for mutual TLS (mTLS). Must be set together with `BB_CLIENT_CERT`. Equivalent flag: `--client-key`.
`BB_INSECURE_SKIP_VERIFY`	unset	`true` disables TLS certificate verification. Prints a warning on every invocation. Equivalent flag: `--insecure-skip-verify`.
`HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`	unset	Standard proxy configuration, honoured for all `bb` HTTP traffic. Lowercase spellings work too.

See Networks, Proxies and TLS for how these interact, and for the difference between bb's own requests and the git subprocesses it starts.

Repository context¶

Variable	Default	Effect
`BITBUCKET_PROJECT_KEY`	`TEST`	Project key used when `--repo` is omitted and no repository can be inferred from a git remote.
`BITBUCKET_REPO_SLUG`	none	Repository slug, used with `BITBUCKET_PROJECT_KEY`.

BITBUCKET_PROJECT_KEY defaults to TEST

That default is a leftover from the test harness. It means a command with no --repo, no inferable git remote and no BITBUCKET_PROJECT_KEY will address a project literally named TEST rather than telling you the context is missing. If you get a confusing "project does not exist" error, this is usually why. Set BITBUCKET_PROJECT_KEY explicitly, or pass --repo.

Webhook credentials¶

Variable	Default	Effect
`BB_WEBHOOK_SECRET`	none	Shared secret for `webhook create` and `webhook update`, used to sign deliveries. There is no flag that takes it as a value (ADR-047); the alternative is `--secret-stdin`.
`BB_WEBHOOK_PASSWORD`	none	Password for the endpoint's basic authentication, paired with `--credentials-username`. The alternative is `--credentials-password-stdin`.

An empty value counts as unset. A --*-stdin flag wins over the variable, and --no-secret / --no-credentials override both — a variable exported for every command must not make removing a credential impossible. See Webhook Secrets for how both are read, and what bb refuses to print.

Interactivity¶

bb prompts only when a person is there to answer, and decides that in one place (ADR-072). These two variables are how you tell it nobody is.

Variable	Default	Effect
`BB_NO_PROMPT`	unset	Any value other than `0`, `false` or empty turns prompting off for every command in the process. A command that then needs a value it cannot ask for fails naming the flag that would have supplied it, rather than falling back to a default. Equivalent flag: `--no-input`.
`BB_NO_PROMPT_VARS`	unset	Comma-separated names of further variables whose presence also means nobody is watching.

bb already treats CI, DEBIAN_FRONTEND, NONINTERACTIVE, TERM=dumb and a list of coding harnesses as proof that nobody is there. BB_NO_PROMPT_VARS is for the harness it has not heard of: set it once in the environment to the variable that harness does set, instead of waiting for a release or passing --no-input on every call.

export BB_NO_PROMPT_VARS=MY_BUILD_RUNNER,ACME_AGENT

--json suppresses prompting on its own: a machine reading structured output is not a person who can answer a question.

Updates¶

Variable	Default	Effect
`BB_DISABLE_UPDATE`	unset	`1` or `true` disables `bb update`. The command explains that it is disabled and points at your system package manager. Administrative policy can disable it too, and is reported separately.
`BB_UPDATE_BASE_URL`	GitHub releases	Base URL the updater fetches manifests and artifacts from, for an internal mirror. The `--base-url` flag wins over it; it wins over the workspace, stored and system configuration.
`BB_ALLOW_HTTP_UPDATE`	unset	`1` or `true` permits a plain-HTTP release mirror, as `bb update --allow-http` does for one run; update URLs are otherwise `https` only. Refused when policy sets `allow_http_update: false`.

These three are the exception to the .env rule above: bb update reads them from the real environment only.

Update trust is settable from system policy only

BB_UPDATE_TRUSTED_ROOT, BB_UPDATE_SIGNATURE_IDENTITY and BB_ALLOW_UNVERIFIED_UPDATE are deliberately not read from the environment. A variable that could redirect the trust root would let anything able to set a variable in your shell approve its own update. Configure these through system policy instead — see System Policy.

BB_DISABLE_UPDATE and BB_UPDATE_BASE_URL are honoured because neither weakens verification: the first only refuses to update, and an artifact from a mirror still has to pass the same signature check. BB_ALLOW_HTTP_UPDATE weakens the connection rather than the signature check, and policy can refuse it.

Output and diagnostics¶

Variable	Default	Effect
`BB_LOG_LEVEL`	`error`	Diagnostic verbosity: `error`, `warn`, `info`, `debug`. Diagnostics go to stderr, so they never corrupt `--json` output on stdout. Equivalent flag: `--log-level`.
`BB_LOG_FORMAT`	`text`	`text` or `jsonl`. Equivalent flag: `--log-format`.
`NO_COLOR`	unset	Any value disables coloured output, following no-color.org. Equivalent flag: `--no-color`.
`BB_ERROR_HARVEST`	unset	Path to a file recording every response Bitbucket refuses, with the request that provoked it. Useful when a failure is hard to describe: set it, reproduce the problem once, and attach the file. Unset, nothing is opened.

For a report of what went wrong, --log-level debug --log-format jsonl gives a structured trace worth attaching to an issue. BB_ERROR_HARVEST is the narrower companion: the trace shows what bb did, the harvest file shows exactly what the server sent back.

Shell completion¶

Variable	Default	Effect
`BB_COMPLETION_TIMEOUT`	`1200ms`	How long one tab press may take, as a Go duration, before it gives up and offers nothing.
`BB_COMPLETION_DEBUG`	unset	Any value prints why a completion came back empty, when one is run by hand. See When nothing is offered.
`BB_ACTIVE_HELP`	unset	`0` turns off the hints bash and zsh show under the prompt.

Development only¶

These exist for this repository's own test suite. They are not part of the supported interface and may change without notice.

Variable	Effect
`BB_BLOCK_EXTERNAL_NETWORK`	`1` makes any HTTP request to a non-loopback host fail immediately. Used so unit tests cannot reach the internet.