Skip to main content
Every setting in a Cortex CLI config file can also be set as an environment variable, and a few things can only be set that way. Variables are the right tool when the value changes per shell, per machine or per CI job: which account to use, where the config lives, whether tools run in the cloud or on a connected computer. This page lists the variables the CLI reads, grouped the way the product groups them, and says what each one overrides. Values are never documented here: put secrets in your OS keyring or your CI secret store, not in a shell profile that gets committed or shared.

​
Precedence

Environment variables sit between config files and command-line flags in precedence: a flag beats a variable, a variable beats a config file. So --sandbox on the command line wins over anything in your environment, and your environment wins over ~/.cortex/config.toml.

​
Locations

The home directory resolves in the order CORTEX_CONFIG_DIR, then CORTEX_HOME, then ~/.cortex. See Data locations for what ends up in each directory.

​
Account

Interactive use should prefer cortex login, which stores the session in the OS keyring. See Sign in to the CLI.

​
Where tools run

This PC and SSH require an already connected Code session. Cortex will not create one for you and will not quietly substitute Cortex Cloud. See Cloud, This PC, and SSH.

​
Model selection

​
Logging and diagnostics

CORTEX_DIAGNOSTICS_DIR is the opt-in switch for writing diagnostic files at all. CLI troubleshooting has the allowlist, the size caps and the retention window.

​
Set for you, not by you

These are populated by Cortex for the processes it spawns. A plugin can read them; you should not set them yourself. Cortex also sets a small number of further variables for its own task routing. They are not a supported surface and setting them yourself is not meaningful. Hooks do not get an environment of their own. A hook belongs to a plugin and runs inside the plugin runtime rather than as a command Cortex spawns for it, so there are no hook-specific variables to read. See Hooks.

​
Standard variables Cortex respects

​
Checking what is in effect

That prints the effective configuration after every layer has been merged, which is the fastest way to find out whether a variable or a config file won. If the answer surprises you, check for a project .cortex/config.toml: it overrides your own config file, though not your environment. See Configuration.
The CLI also reads a handful of capture and test variables that exist for people working on the CLI itself. They are not part of the supported surface. The only one a normal user tends to want is CORTEX_CURSOR_BLINK, which overrides blink behaviour in the composer.