Trace CLI — Configuration

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

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

`buildwithtrace config`

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)
`llm.model`	provider model ID	—	Model to use with a BYOK provider

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`

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

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.

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.

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:

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.

Command Line (CLI)

Partner API

Reference

Platforms

Help

Configuration

`buildwithtrace config`

Config keys

Environments

Environment variables

Files on disk

Credential storage

Analytics

​buildwithtrace config

​Config keys

​Environments

​Environment variables

​Files on disk

​Credential storage

​Analytics

`buildwithtrace config`

Config keys

Environments

Environment variables

Files on disk

Credential storage

Analytics