> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/developer-tools/terra-cli/configuration.md).

# 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.

```bash
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`

```bash
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.

{% hint style="info" %}
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.
{% endhint %}

## Profiles

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

```bash
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.

```bash
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 the update notice          |
| `TERRA_NO_UPDATE_NOTIFIER`   | Turn off the "a new release is available" notice        |
| `NO_COLOR`                   | Disable colored output                                  |
| `CLICOLOR`, `CLICOLOR_FORCE` | Color, per the CLICOLOR convention                      |

## 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:

```bash
export TERRA_CLI_TELEMETRY_OPTOUT=1
```

`DO_NOT_TRACK=1` also works, and is honored across tools that follow [that convention](https://donottrack.sh). Either variable is checked before anything is collected.