Configuration

How the Terra CLI resolves settings, picks an environment, and uses profiles and environment variables.

Configuration lives in config.toml under the CLI's config directory. That is $XDG_CONFIG_HOME/terra when the variable is set, and otherwise the OS config directory: ~/Library/Application Support/terra on macOS, ~/.config/terra on Linux, and %AppData%\terra on Windows. Set TERRA_CONFIG_DIR to move it.

terra config --list
terra config --get default_environment
terra config --set default_environment dev-prod
terra config --unset default_environment

The settable keys are base_url and default_environment. Everything else in the file is metadata the CLI writes. Tokens are never stored there, so the file is safe to print.

Precedence

Every setting resolves the same way:

1. A flag on the command

2. An environment variable

3. The config file

4. The built-in default

Environments

Most commands act on one environment, identified by its dev-id. A command resolves the environment in this order:

1. --env <name or dev-id>

2. TERRA_ENV

3. The profile default, set with terra environments use

terra environments use Production   # set the default
terra users list                    # uses it
terra users list --env Staging      # overrides it once

A command that needs an environment and finds none fails before sending anything, and says how to supply one.

Names and dev-ids

Wherever a dev-id is accepted, the environment's name works too, matched without regard to case. A value that is exactly a dev-id is used as one, so a name can never shadow a real dev-id. A name shared by two environments is refused, naming both dev-ids.

terra environments use stores the dev-id, never the name, so renaming an environment later cannot repoint the default. It also checks that the environment exists, so a typo fails there rather than on every later command. --no-verify stores the value as typed.

The environment list is cached for a day, so resolving a name costs no request once it has been read. terra environments use refreshes the cache first.

A destructive command prints the resolved environment before asking for confirmation. A dev-id that came from configuration or TERRA_ENV is otherwise invisible in the command you typed.

Profiles

A profile is a named set of settings with its own stored token, so several accounts or deployments can coexist on one machine.

terra --profile staging login
terra --profile staging environments list

TERRA_PROFILE selects a profile for a whole shell. The flag wins where both are set.

export TERRA_PROFILE=staging

Environment variables

Variable	Purpose
TERRA_ADMIN_TOKEN	Use this token instead of the stored one
TERRA_ENV	Default environment
TERRA_PROFILE	Select a config profile. --profile overrides it.
TERRA_CONFIG_DIR	Override the config directory
TERRA_BASE_URL	Point the admin API at a different deployment
TERRA_DATA_BASE_URL	Point the data API somewhere other than the derived URL
TERRA_API_KEY	The data API key, instead of fetching the environment's
TERRA_KEYRING=file	Store the token in a 0600 file instead of the keyring
TERRA_BROWSER=none	Never open a browser
TERRA_SKILLS_INDEX_URL	Read the agent skill catalog from somewhere else
TERRA_CLI_TELEMETRY_OPTOUT	Turn off usage reporting
DO_NOT_TRACK	Turn off usage reporting and automatic update activity
TERRA_NO_AUTO_UPDATE=1	Keep update notices without installing updates
TERRA_NO_UPDATE_NOTIFIER	Turn off automatic update checks and installs
NO_COLOR	Disable colored output
CLICOLOR, CLICOLOR_FORCE	Color, per the CLICOLOR convention

For update behavior and explicit updates, see Installation.

Telemetry

Released builds report which commands are run and how they turned out, along with the CLI version, operating system, architecture, install method, and whether a coding agent is driving it.

Flag values, positional arguments, tokens, request and response bodies, file paths, environment variables, and the contents of the config file are never collected.

To turn it off:

export TERRA_CLI_TELEMETRY_OPTOUT=1

DO_NOT_TRACK=1 also works, and is honored across tools that follow that convention. Either variable is checked before anything is collected.