> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithtrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure the Trace CLI — config.toml, environment variables, backend environments, and where credentials are stored.

The CLI reads settings from three places, in priority order:

1. **Environment variables** (highest priority — great for CI)
2. **`config.toml`** (persistent settings via `buildwithtrace config set`)
3. **Built-in defaults**

## `buildwithtrace config`

```bash theme={null}
buildwithtrace config set <key> <value>
buildwithtrace config get <key>
buildwithtrace config list
```

`buildwithtrace config list` prints every stored setting plus the *effective* environment and backend URL.

### Config keys

| Key             | Values                                   | Default      | Description                                                                                                                                   |
| --------------- | ---------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `env`           | `production`, `staging`, `local`         | `production` | Which Trace backend to talk to                                                                                                                |
| `backend`       | *(alias for `env`)*                      | —            | Friendly alias; `config set backend staging` == `config set env staging`                                                                      |
| `api_version`   | `latest`, `v4`, `v3`                     | `latest`     | API version prefix. `latest` resolves server-side to the newest backend API (freshest agent tools + prompt); pin `v4`/`v3` only for stability |
| `output.format` | `text`, `json`                           | `text`       | Default output format                                                                                                                         |
| `llm.provider`  | `trace`, `anthropic`, `openai`, `gemini` | `trace`      | Active model provider (see [BYOK](/resources/cli-byok))                                                                                       |
| `llm.model`     | provider model ID                        | —            | Model to use with a BYOK provider                                                                                                             |

```bash theme={null}
buildwithtrace config set env staging
buildwithtrace config set output.format json
buildwithtrace config list
```

## Environments

The `env` setting selects the backend. `production` is correct for everyone except Trace developers.

| Environment  | Backend URL                      |
| ------------ | -------------------------------- |
| `production` | `https://api.buildwithtrace.com` |
| `staging`    | Trace internal staging           |
| `local`      | `http://localhost:8000`          |

```bash theme={null}
buildwithtrace config set env production   # the default
buildwithtrace doctor                      # confirms the effective backend URL
```

## Environment variables

| Variable                                                       | Description                                                                                           |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `TRACE_API_TOKEN`                                              | Auth token; used automatically when set (CI/headless). Accepts a `trace_pat_...` PAT or a session JWT |
| `TRACE_API_KEY`                                                | Token alias read by the SDKs (`TRACE_API_TOKEN` is also accepted by the Python SDK)                   |
| `TRACE_ENV`                                                    | Override the CLI backend environment (`production`/`staging`/`local`)                                 |
| `TRACE_BASE_URL`                                               | Override the API base URL directly (used by the **SDKs**; the CLI uses `TRACE_ENV`)                   |
| `TRACE_FRONTEND_URL`                                           | Override the login-page origin used by the browser deeplink login                                     |
| `TRACE_API_VERSION`                                            | Override the API version (`latest` (default) / `v4` / `v3`)                                           |
| `TRACE_CONFIG_DIR`                                             | Override the config/credentials directory                                                             |
| `TRACE_OUTPUT_FORMAT`                                          | Set to `json` to force JSON output                                                                    |
| `TRACE_JSON`                                                   | Backing env var for the global `--json` flag                                                          |
| `TRACE_NO_INTERACTIVE`                                         | Disable prompts (also implied by `CI`)                                                                |
| `CI`                                                           | When set, enables JSON output + non-interactive mode, and auto-disables analytics + the update check  |
| `TRACE_NO_ANALYTICS`                                           | Disable PostHog usage analytics                                                                       |
| `DO_NOT_TRACK`                                                 | Cross-tool standard — also disables analytics                                                         |
| `TRACE_NO_UPDATE_CHECK`                                        | Set to `1` to disable the "new version available" notice                                              |
| `TRACE_NO_REPORTS`                                             | Disable automatic error/generation-failure reports                                                    |
| `TRACE_NO_UPDATE_CHECK`                                        | Disable the "a newer `buildwithtrace` is available on PyPI" notification                              |
| `TRACE_ENGINE_PATH`                                            | Use a specific engine binary for ERC/DRC/export                                                       |
| `POSTHOG_API_KEY` / `POSTHOG_HOST`                             | Override analytics destination                                                                        |
| `HTTP_PROXY` / `HTTPS_PROXY`                                   | Standard proxy support (checked by `buildwithtrace doctor`)                                           |
| `VISUAL` / `EDITOR`                                            | Editor used by `buildwithtrace rules edit` and inline editing                                         |
| `TRACE_LLM_PROVIDER` / `TRACE_LLM_API_KEY` / `TRACE_LLM_MODEL` | BYOK routing for the **SDKs** (set once via env). See [BYOK](/resources/cli-byok)                     |
| `ANTHROPIC_API_KEY`                                            | BYOK key for Anthropic (read by the CLI's `byok`)                                                     |
| `OPENAI_API_KEY`                                               | BYOK key for OpenAI                                                                                   |
| `GEMINI_API_KEY` / `GOOGLE_API_KEY`                            | BYOK key for Gemini                                                                                   |
| `KICAD_SYMBOL_DIR` / `KICAD_FOOTPRINT_DIR`                     | Extra library search paths for local conversion                                                       |
| `ALTIUM_PREFERRED_VERSION`                                     | Pin a specific Altium Designer version for the bridge                                                 |

<Note>
  The Python (`buildwithtrace-sdk`) and Node (`@buildwithtrace/sdk`) SDKs read the same `TRACE_API_TOKEN` / `TRACE_API_KEY` for auth and `TRACE_ENV` for the backend environment, so a machine already set up for the CLI works for the SDKs with no extra configuration. See [SDKs](/resources/cli#sdks-build-on-trace-from-code).
</Note>

## Files on disk

Config and credentials live in the platform config directory (override with `TRACE_CONFIG_DIR`):

```
<config-dir>/
├── config.toml          ← settings (buildwithtrace config set ...)
├── credentials.json     ← token/key fallback (only if no keychain; chmod 0600)
├── sessions/            ← conversation session data
└── logs/                ← CLI logs
```

Typical locations:

* **macOS** — `~/Library/Application Support/trace/`
* **Linux** — `~/.config/trace/`
* **Windows** — `%APPDATA%\buildwithtrace\trace\`

Run `buildwithtrace config list` if you're unsure — it reports the effective paths and values.

## Credential storage

Auth tokens and BYOK keys are stored in your **OS keychain** under the service name `com.buildwithtrace.cli`:

* macOS — Keychain
* Windows — Credential Manager
* Linux — Secret Service (GNOME Keyring / KWallet)

If no keychain is available (common on headless servers), the CLI falls back to `credentials.json` with `0600` permissions. Secrets are **never** written to the plaintext `config.toml`.

```bash theme={null}
buildwithtrace auth login     # stores tokens
buildwithtrace auth logout    # clears tokens
buildwithtrace byok clear anthropic   # clears a BYOK key
```

## Analytics

The CLI (and the SDKs) send anonymous, privacy-first usage analytics to PostHog to help improve the product. Every event is tagged with the client (`cli` / `sdk-python` / `sdk-node`).

**What's collected:** command/method names, durations, exit codes, and version/OS info only. A hard PII scrub drops anything that isn't a short enum / number / boolean, so **file contents, file paths, net or component names, and your prompts are never sent**.

**Auto-disabled when:** you're in CI, you've opted out, or it's a source install with no analytics key baked in (those never phone home).

Disable it entirely with either:

```bash theme={null}
export TRACE_NO_ANALYTICS=1   # Trace-specific
export DO_NOT_TRACK=1         # cross-tool standard, also honored
```

Analytics are fire-and-forget and never block or fail a command.