Environment Variables

Most configuration lives in config files, but a few settings can be supplied via environment variables, handy for CI runners, ephemeral shells, and secrets you don’t want to commit.

Common

Variable	Effect
`IRONBEE_SERVICE_API_KEY`	Supplies `service.apiKey` (the shared account API key) without committing it. Takes precedence over every config layer. The credential of choice for CI and the GitHub Action.
`IRONBEE_SERVICE_OAUTH_TOKEN`	Supplies `service.oauthToken` (the personal token from `ironbee login`) without committing it. When both credentials are set, the OAuth token wins.
`IRONBEE_SERVICE_DOMAIN`	Supplies `service.domain`, the stage selector every service URL derives from.
`IRONBEE_API_KEY`	Legacy — supplies the deprecated `collector.apiKey` fallback, which is read only when `service.apiKey` is unset (a recent `ironbee login` writes `service.*`, which then wins). One exception: `ironbee verify` reads it as a deliberate top-priority override.
`IRONBEE_OAUTH_TOKEN`	Legacy — supplies the deprecated `collector.oauthToken` fallback; same caveat as above.
`IRONBEE_TELEMETRY`	Set to `false` to turn off anonymous CLI telemetry for this shell/run, a per-session alternative to the `telemetry.enable` config key.
`IRONBEE_LOG_LEVEL`	Logging verbosity. Set to `debug` to see detailed output when troubleshooting.

# CI: provide the API key from a secret, no file commit
export IRONBEE_SERVICE_API_KEY=sk-...
ironbee import --since 30d --yes

Because these override the files, a merged read (ironbee config get service.apiKey) returns the env value. A layer-scoped read (--project / --global / --local) bypasses env and shows only what’s on disk.

Verification jobs

ironbee verify — the cloud verification-job runner — reads two extra overrides of its own, plus the GitHub Actions context:

Variable	Effect
`IRONBEE_ACCESS_TOKEN`	OAuth access token for the API, overriding `service.oauthToken`.
`IRONBEE_API_URL`	API base URL, overriding `api.url` (the `--api-url` flag wins over both).
`GITHUB_ACTIONS`	When exactly `"true"`, a created job is declared with the `github_actions` trigger (Console visibility only) and secret-header values are masked with `::add-mask::`.
`GITHUB_REPOSITORY` / `GITHUB_SHA` / `GITHUB_REF`	Fill the run’s repository binding: the `owner/repo`, the authoritative commit, and the pull-request number on a PR run.

Issue-tracker credentials

The issue-tracker integrations normally keep their secrets in your global config (~/.ironbee/config.json, written by ironbee integrations <provider> setup). In CI — or anywhere you’d rather source them from a vault — supply them via env instead. Like the collector credentials, these take precedence over every config layer:

Variable	Effect
`IRONBEE_JIRA_API_TOKEN`	Supplies `integrations.jira.apiToken` (Jira Cloud API token). Combine with a file-set `integrations.jira.baseUrl` + `email` for a complete config.
`IRONBEE_JIRA_PAT`	Supplies `integrations.jira.pat` (Jira Server/DC personal access token).
`IRONBEE_LINEAR_API_KEY`	Supplies `integrations.linear.apiKey` (Linear personal API key or OAuth token).

GitHub needs no credential variable — it rides the gh CLI’s own auth (GitHub Actions ships a GH_TOKEN).

Config placeholder bridges

Config placeholders let a committed config carry references that resolve from the environment — the way to override a team default per developer or per CI run without editing a file:

Variable pattern	Feeds	Notes
`IRONBEE_PARAM_<NAME>`	`${param:<name>}` references	Overrides the `params` block for that key. `<name>` maps case-insensitively — `IRONBEE_PARAM_API_URL` fills `${param:api_url}`.
`IRONBEE_ENV_<NAME>`	`${env:<name>}` references	The only environment source a `${env:}` reference can read. `IRONBEE_ENV_STAGING_URL` fills `${env:staging_url}`.

# CI: override a committed ${param:api_url} for this run
export IRONBEE_PARAM_API_URL=https://api.staging.internal

The IRONBEE_PARAM_* / IRONBEE_ENV_* prefixes are reserved for placeholder input — the implied prefix means arbitrary environment variables (secrets, tokens) are structurally unreachable from config text. An empty value counts as unset (the reference falls through to its :- default). IronBee’s own operational env vars never use these prefixes.

Project directory resolution

When a hook or command needs to know which project it’s acting on, IronBee resolves the directory in this order:

The client’s own variable CLAUDE_PROJECT_DIR (Claude Code) or CURSOR_PROJECT_DIR (Cursor), set automatically by the host
IRONBEE_PROJECT_DIR, an explicit override you can set
The current working directory

You normally don’t set these yourself; the AI client provides them. IRONBEE_PROJECT_DIR is the escape hatch for scripted or non-standard setups.

Advanced

Rarely needed, mostly for internal wiring and test harnesses:

Variable	Effect
`IRONBEE_CLIENT`	Tells a hook runner which client it’s acting as (the `--client` flag overrides it). Set by the installed hook config.
`IRONBEE_RUNTIME_LOCATION`	Overrides `runtime.location` for this process — `external` (default, per-session data under `~/.ironbee/projects/<token>/`) or `in-project` (`<project>/.ironbee/sessions/`). Takes precedence over the config layers; mainly used by the test suite.
`IRONBEE_BIN`	Overrides the path to the `ironbee` binary used when spawning background workers.
`IRONBEE_COLLECTOR`	Set to `false` to disable Collector sends entirely (used by the test harness).
`IRONBEE_CURSOR_USER_DIR`	Overrides where IronBee looks for Cursor’s local user data (the `state.vscdb` store) when reading Cursor session analytics. Defaults to Cursor’s standard per-OS location; mainly for non-standard installs and tests.
`IRONBEE_NO_AUTO_RERENDER`	Disables the auto re-render of registered projects after a structure-changing upgrade. A kill switch for CI and locked-down machines.
`IRONBEE_NO_PREFETCH`	Global kill-switch for the devtools prefetch — any value other than empty/`0`/`false` skips the npx cache warm on `install`, upgrade re-renders, `ironbee browser enable`, and `ironbee devtools prefetch`.
`IRONBEE_GH_AUTHENTICATED`	Forces the GitHub issue-tracker activation probe deterministically — `1`/`true` = active, `0`/`false` = inactive — bypassing the `gh auth status` check. For CI/test environments where a deterministic result is wanted. `integrations.github.enable: false` still suspends it regardless.
`CI`	When truthy (`true` / `1`), also short-circuits the upgrade auto re-render — belt-and-suspenders so a CI that allocates a pseudo-TTY can’t hang on the confirmation prompt.

Introduction

Concepts

CLI

GitHub Action

Help

Environment Variables

Common

Verification jobs

Issue-tracker credentials

Config placeholder bridges

Project directory resolution

Advanced

What’s next?

Configuration

Runtime files

​Common

​Verification jobs

​Issue-tracker credentials

​Config placeholder bridges

​Project directory resolution

​Advanced

​What’s next?

Configuration

Runtime files

Common

Verification jobs

Issue-tracker credentials

Config placeholder bridges

Project directory resolution

Advanced

What’s next?