Common
| Variable | Effect |
|---|---|
IRONBEE_API_KEY | Supplies collector.apiKey without committing it. Takes precedence over every config layer. Combine with a file-set collector.url for a complete config. The credential of choice for CI and the GitHub Action. |
IRONBEE_OAUTH_TOKEN | Supplies collector.oauthToken (the personal token from ironbee login) without committing it. Takes precedence over every config layer. When both this and IRONBEE_API_KEY are set, the OAuth token wins. |
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. |
Because
IRONBEE_API_KEY overrides the files, a merged read (ironbee config get collector.apiKey) returns the env value. A layer-scoped read (--project / --global / --local) bypasses env and shows only what’s on disk.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}. |
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) orCURSOR_PROJECT_DIR(Cursor), set automatically by the host IRONBEE_PROJECT_DIR, an explicit override you can set- The current working directory
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. |
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. |
What’s next?
Configuration
The full config-key reference, the file-based equivalents of these overrides.
Runtime files
Where config and credentials are stored on disk.