Skip to main content
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

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

KeyValuesDefaultDescription
envproduction, staging, localproductionWhich Trace backend to talk to
backend(alias for env)—Friendly alias; config set backend staging == config set env staging
api_versionlatest, v4, v3latestAPI version prefix. latest resolves server-side to the newest backend API (freshest agent tools + prompt); pin v4/v3 only for stability
output.formattext, jsontextDefault output format
llm.providertrace, anthropic, openai, geminitraceActive model provider (see BYOK)
llm.modelprovider 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.
EnvironmentBackend URL
productionhttps://api.buildwithtrace.com
stagingTrace internal staging
localhttp://localhost:8000
buildwithtrace config set env production   # the default
buildwithtrace doctor                      # confirms the effective backend URL

​
Environment variables

VariableDescription
TRACE_API_TOKENAuth token; used automatically when set (CI/headless). Accepts a trace_pat_... PAT or a session JWT
TRACE_API_KEYToken alias read by the SDKs (TRACE_API_TOKEN is also accepted by the Python SDK)
TRACE_ENVOverride the CLI backend environment (production/staging/local)
TRACE_BASE_URLOverride the API base URL directly (used by the SDKs; the CLI uses TRACE_ENV)
TRACE_FRONTEND_URLOverride the login-page origin used by the browser deeplink login
TRACE_API_VERSIONOverride the API version (latest (default) / v4 / v3)
TRACE_CONFIG_DIROverride the config/credentials directory
TRACE_OUTPUT_FORMATSet to json to force JSON output
TRACE_JSONBacking env var for the global --json flag
TRACE_NO_INTERACTIVEDisable prompts (also implied by CI)
CIWhen set, enables JSON output + non-interactive mode, and auto-disables analytics + the update check
TRACE_NO_ANALYTICSDisable PostHog usage analytics
DO_NOT_TRACKCross-tool standard — also disables analytics
TRACE_NO_UPDATE_CHECKSet to 1 to disable the “new version available” notice
TRACE_NO_REPORTSDisable automatic error/generation-failure reports
TRACE_ENGINE_PATHUse a specific engine binary for ERC/DRC/export
POSTHOG_API_KEY / POSTHOG_HOSTOverride analytics destination
HTTP_PROXY / HTTPS_PROXYStandard proxy support (checked by buildwithtrace doctor)
VISUAL / EDITOREditor used by buildwithtrace rules edit and inline editing
TRACE_LLM_PROVIDER / TRACE_LLM_API_KEY / TRACE_LLM_MODELBYOK routing for the SDKs (set once via env). See BYOK
ANTHROPIC_API_KEYBYOK key for Anthropic (read by the CLI’s byok)
OPENAI_API_KEYBYOK key for OpenAI
GEMINI_API_KEY / GOOGLE_API_KEYBYOK key for Gemini
KICAD_SYMBOL_DIR / KICAD_FOOTPRINT_DIRExtra library search paths for local conversion
ALTIUM_PREFERRED_VERSIONPin a specific Altium Designer version for the bridge

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