Trace CLI

The Trace CLI is in active alpha (v0.1.0). Everything on this page reflects the shipping command surface. The AI commands (chat, agent, plan, review, ask) run through the Trace backend — free accounts get ask; agent/plan require a paid plan, free agent credits, or an active legacy trial. The local commands (erc, drc, gerbers, export, convert, rules, history, index) work without a subscription.

What it is

buildwithtrace is a terminal interface for Trace’s AI-powered EDA tools. On macOS and Windows, it requires the Trace desktop app to be installed (the CLI uses the desktop app’s local engine). On Linux, the CLI downloads a standalone engine automatically on first use — no desktop app needed.

Design with AI — buildwithtrace chat, buildwithtrace agent, and buildwithtrace plan give you the full agentic design loop, with file edits, tool execution, and plan mode, against your local .kicad_sch / .kicad_pcb / .trace_sch / .trace_pcb files.
Validate locally — buildwithtrace erc, buildwithtrace drc, and buildwithtrace gerbers run on a bundled engine, no cloud round-trip required. Perfect for CI.
Convert anything — buildwithtrace convert turns Altium (.SchDoc / .PcbDoc / .PrjPcb) into KiCad with netlist-accurate connectivity, and moves losslessly between KiCad and Trace’s text DSL (.trace_sch / .trace_pcb).
Manufacture — buildwithtrace dfm, buildwithtrace bom, buildwithtrace components, and buildwithtrace order take you from design to fab.
Integrate — buildwithtrace mcp serve exposes Trace as a Model Context Protocol server so Cursor, Claude Desktop, or any MCP client can drive it. The GitHub Action drops it into CI.
Build on Trace — the Python (buildwithtrace-sdk) and Node (@buildwithtrace/sdk) SDKs are standalone agent clients: they run the client-side tool-execution loop themselves, so agent and plan work directly from your own code without the CLI installed. See SDKs.

The same Trace account, plan, quota, versions, and teams back both the desktop app and the CLI. Work you do in one shows up in the other.

How it fits together

┌─────────────────────────────────────────────────────────┐
│  buildwithtrace (CLI)                                   │
│  • Local engine: ERC / DRC / Gerbers / PDF / SVG / STEP │
│  • Local converters: Altium ↔ KiCad ↔ Trace DSL         │
│  • Offline EDA index, rules, history (no network)       │
├─────────────────────────────────────────────────────────┤
│  api.buildwithtrace.com  (the same backend the app uses)│
│  • AI: chat / agent / plan / review / ask (SSE stream)  │
│  • Components, BOM, DFM, orders, versions, teams, billing│
└─────────────────────────────────────────────────────────┘

The “local engine” IS the Trace desktop app’s command-line binary (trace-cli). On macOS and Windows, the desktop app must be installed — the CLI detects it automatically. On Linux, if you don’t have the desktop app installed, the CLI downloads a standalone engine on first use. Either way, the commands work identically.

AI requests stream over Server-Sent Events. Tool calls (read file, write, grep, run ERC/DRC, snapshot, etc.) are dispatched back to the CLI and executed on your machine, against your files — your designs never have to leave your disk for the AI to work on them.

Bringing your own model key? buildwithtrace byok set anthropic|openai|gemini routes the AI through your provider (billed to you, not your Trace quota) while still using Trace’s EDA tools and prompts. See Bring Your Own Key.

Install

The CLI is a Python package (buildwithtrace) and requires Python 3.10+. It installs a single command: buildwithtrace. (There’s no trace binary — that name collides with the macOS system /usr/bin/trace.)

Want a shorter command? Add your own shell alias — alias trace=buildwithtrace. Note this shadows the macOS system /usr/bin/trace, so skip it on macOS unless you’re sure you don’t need the system tool.

pip
pipx (isolated)
Homebrew
npm
GitHub Actions

pip install buildwithtrace

pipx install buildwithtrace

brew install buildwithtrace/tap/buildwithtrace

npm install -g buildwithtrace

The npm package downloads the Python wheel into an isolated virtualenv on postinstall. You still need Python 3.10+ on your machine.

- uses: buildwithtrace/github-action@v1
  with:
    token: ${{ secrets.TRACE_API_TOKEN }}

See Automation & CI/CD.

Verify the install:

buildwithtrace --version
buildwithtrace doctor      # checks API connectivity, auth, engine, Python, model provider

Authenticate

buildwithtrace auth login

This opens your browser to the Trace login page ({frontend}/login?callback=http://localhost:PORT/callback) and waits on a loopback callback. You sign in in the browser — password, Google, GitHub, or magic link, with the captcha solved there — and the page bounces the tokens back to the CLI. (The old --provider flag is deprecated; the provider is now chosen in the browser.) Tokens are stored in your OS keychain (com.buildwithtrace.cli), falling back to a 0600 file if no keychain is available. For headless / CI / SSH machines, skip the browser:

# Recommended for CI — a long-lived Personal Access Token (see below)
export TRACE_API_TOKEN=trace_pat_xxx

# Or log in with a token explicitly
buildwithtrace auth login --token trace_pat_xxx

# Or print the login URL to open on another machine (no auto-open)
buildwithtrace auth login --no-browser

# Or non-interactive password login
buildwithtrace auth login --email you@example.com --password '...'

Personal Access Tokens (CI/automation)

A browser login gives you a short-lived (~1h) session JWT — fine for an immediate pipe, but it expires. For CI, mint a long-lived Personal Access Token (trace_pat_..., shown once):

buildwithtrace auth token --create --name ci-bot
# optional: --scope mcp:all (default) / --scope partner:read, repeatable; --expires-days 90
export TRACE_API_TOKEN=trace_pat_...

buildwithtrace auth token --list           # your PATs (prefixes, scopes, expiry, last used)
buildwithtrace auth token --revoke <id>    # delete a PAT
buildwithtrace auth token                  # (no flags) print the CURRENT session token to stdout

Scopes are mcp:all (default — full CLI/MCP access) or partner:read. You can also create PATs in the dashboard (Settings → Developer → Create Token), which has a scope + expiry picker.

Creating, listing, and revoking tokens requires an interactive login session (a browser/email login) — a PAT cannot manage tokens. This keeps a leaked PAT from minting more tokens or revoking your others. (Enforced server-side.)

Check who you are and your plan/quota at any time:

buildwithtrace whoami
buildwithtrace auth status

Quick start

# Ask a question — read-only, no files touched (works on the free plan)
buildwithtrace ask "What decoupling caps does an STM32F4 need?"

# Full interactive design session against a project
buildwithtrace chat --project ./my-board/

# One-shot, single-instruction edit (writes auto-approved)
buildwithtrace agent "Add a 100nF decoupling cap to every IC power pin" --project ./my-board/

# Multi-step plan mode: research → questions → plan → execute
buildwithtrace plan "Design a USB-C PD trigger board for 20V output"

# AI design review, written to a file
buildwithtrace review ./my-board/ --focus thermal,power --output review.md

# Local validation (uses the bundled engine — no account needed)
buildwithtrace erc ./my-board/board.kicad_sch
buildwithtrace drc ./my-board/board.kicad_pcb
buildwithtrace gerbers ./my-board/board.kicad_pcb --output ./fab/

# Convert an Altium project to KiCad
buildwithtrace convert project ./LegacyBoard/ --output ./kicad-out/

The command surface at a glance

Command	What it does	Runs
`buildwithtrace chat`	Interactive AI design session	Backend
`buildwithtrace ask`	One-shot read-only question	Backend
`buildwithtrace agent`	Single auto-approved instruction	Backend
`buildwithtrace plan`	Research → plan → execute	Backend
`buildwithtrace review`	AI design review	Backend
`buildwithtrace signal`	Trace a net/component through connectivity	Backend
`buildwithtrace erc` / `drc`	Electrical / design rule checks	Local engine
`buildwithtrace gerbers`	Gerber + drill export	Local engine
`buildwithtrace export`	PDF / SVG / netlist / BOM / STEP / pos	Local engine
`buildwithtrace convert`	Altium ↔ KiCad ↔ `.trace_sch`/`.trace_pcb`	Local
`buildwithtrace index`	Offline component/net lookup	Local
`buildwithtrace rules`	Manage `.trace/rules.md`	Local
`buildwithtrace history`	Browse `.history` autosave (read-only)	Local
`buildwithtrace components`	Search / check parts	Backend
`buildwithtrace bom`	Generate / enrich BOMs	Backend
`buildwithtrace generate`	Generate symbols / footprints	Backend
`buildwithtrace dfm`	DFM autofill / checks	Backend
`buildwithtrace order`	Manufacturing orders	Backend
`buildwithtrace versions`	Schematic version snapshots	Backend
`buildwithtrace teams`	Team workspaces	Backend
`buildwithtrace billing`	Plan, quota, upgrade	Backend
`buildwithtrace share`	Shareable conversation links	Backend
`buildwithtrace altium`	Live Altium Designer bridge	Backend + bridge
`buildwithtrace byok`	Bring your own LLM key	Local
`buildwithtrace mcp`	MCP server for AI assistants	Local
`buildwithtrace config`	CLI configuration	Local
`buildwithtrace engine`	Manage the local engine binary	Local
`buildwithtrace doctor`	Diagnose environment & connectivity	Local
`buildwithtrace whoami`	Show current user	Local

See the full CLI Command Reference for every flag and argument.

SDKs (build on Trace from code)

Prefer to drive Trace from your own scripts, services, or apps instead of the terminal? Two official SDKs wrap the same backend the CLI and desktop app use. They are standalone agent clients — each runs the client-side tool-execution loop itself, so the full agentic design loop (agent and plan, with file edits and tool calls executed locally against your files) works directly from the SDK, with no CLI installed.

Python
Node

pip install buildwithtrace-sdk

from buildwithtrace_sdk import Trace

trace = Trace()  # reads TRACE_API_TOKEN / TRACE_API_KEY from the environment

Requires Python 3.10+. Import root is buildwithtrace_sdk (distinct from the buildwithtrace CLI package).

npm install @buildwithtrace/sdk

import { Trace } from "@buildwithtrace/sdk";

const trace = new Trace(); // reads TRACE_API_TOKEN / TRACE_API_KEY from the environment

The SDKs authenticate the same way as the CLI — a Trace account plus TRACE_API_TOKEN (or TRACE_API_KEY), see Configuration — and hit the same backend, so your plan, quota, versions, and teams are shared across the desktop app, the CLI, and the SDKs.

The SDKs are a separate product from the buildwithtrace CLI. The CLI installs (pip install buildwithtrace, brew install buildwithtrace/tap/buildwithtrace, npx buildwithtrace) stay exactly as documented above — buildwithtrace-sdk / @buildwithtrace/sdk are additional packages for programmatic use, not replacements.

Security

The CLI executes AI tool calls (read, write, search-replace, delete) locally on your machine, behind the same sandbox the desktop app uses:

Project-directory sandbox — every file path is resolved (Path.resolve(), symlink-safe) and must live inside the project directory. Paths that escape it are rejected.
Extension allowlist — reads/writes are limited to EDA file types: .trace_sch, .trace_pcb, .kicad_sch, .kicad_pcb, .kicad_sym, .kicad_mod, Altium (.SchDoc, .PcbDoc, .SchLib, .PcbLib, .PrjPcb), plus .svg, .zip, .gbr, .drl, .md, and the fp-lib-table / sym-lib-table files. Anything else is blocked.
Write approval — in buildwithtrace chat, write/search-replace/delete tools prompt for approval before touching disk. Pass --yes to auto-approve (e.g. for scripted runs). buildwithtrace agent auto-approves by design; buildwithtrace ask and buildwithtrace review never write.
Credentials — auth tokens and BYOK keys live in your OS keychain (service com.buildwithtrace.cli), never in plaintext config. See Configuration.

Your design files never need to leave your machine for local commands (erc, drc, gerbers, export, convert, index). AI commands stream the relevant file content to the backend so the model can reason about it; tool execution always happens locally.

Caveats & FAQ

Local commands require the Trace desktop app (or KiCad)

buildwithtrace erc, drc, gerbers, and export are thin wrappers around the Trace desktop app’s C++ engine binary (trace-cli). You need the desktop app (or KiCad) installed on the same machine. The CLI cannot run these commands without it.

The CLI searches these locations for the engine:

Priority	Location	Notes
1	`TRACE_ENGINE_PATH` env var	Explicit override
2	`/Applications/Trace.app/` (macOS)	Desktop app bundle
3	`%LOCALAPPDATA%\Programs\Trace\` (Windows)	Desktop app install
4	`/usr/bin/trace-cli` or `/opt/trace/` (Linux)	System install or AppImage
5	`kicad-cli` in PATH	KiCad fallback (same engine, different branding)

If none are found, the CLI shows: “Trace/KiCad CLI not found. Install Trace from buildwithtrace.com” Why not bundle it? The engine is ~150 MB of compiled C++ with platform-specific GUI dependencies. Bundling it into a Python wheel would make installation impractical. The architecture is: lightweight Python CLI orchestrates → heavyweight C++ engine executes. Don’t want the full desktop app? On Linux, the CLI auto-downloads a self-contained engine on first use (~200 MB AppImage). On macOS/Windows, the desktop app is required — it’s a free download at buildwithtrace.com/download.

Which commands need the engine and which don't?

Need the engine (C++ binary):

buildwithtrace erc — Electrical Rule Check
buildwithtrace drc — Design Rule Check
buildwithtrace gerbers — Gerber/drill export
buildwithtrace export — PDF/SVG/STEP export

Pure Python (no engine needed):

buildwithtrace convert — format conversion (Altium ↔ KiCad ↔ Trace)
buildwithtrace index — local project indexing
buildwithtrace rules — TraceRules management
buildwithtrace history — git-based local history (needs git in PATH)
buildwithtrace ask/chat/agent/plan/review — AI commands (need network, not engine)
buildwithtrace auth — authentication
buildwithtrace byok — key management
buildwithtrace doctor — diagnostics

Engine version must match your files

If you save a file with Trace 1.4 and try to run ERC with an older engine (e.g., from a KiCad 8.0 install), you’ll get “Failed to load schematic.” The CLI detects this and suggests updating. Fix: update the desktop app from buildwithtrace.com/download.

Python 3.10+ required (not 3.9 or earlier)

The CLI requires Python 3.10 at minimum. Common pitfalls:

macOS: The system Python (/usr/bin/python3) is often 3.9. Install via brew install python@3.12 or pyenv install 3.12.
Ubuntu 20.04 LTS: Ships Python 3.8. Use the deadsnakes PPA: sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.12.
Symptom: SyntaxError or ImportError on install/import if version is too old.

AI commands require authentication + a paid plan or free agent credits

Command	Free plan (no credits left)	Free agent credits / Legacy trial / Paid
`ask`	✓	✓
`chat`	✗	✓
`agent`	✗	✓
`plan`	✗	✓
`review`	✗	✓

New accounts get free agent credits (~$5 one-time + a small monthly top-up) that unlock the agentic commands until exhausted. The CLI shows a clear error (“Access denied — this feature requires a paid plan”) if your plan doesn’t support the command. Run buildwithtrace auth status to check. If your plan doesn’t allow the mode, the CLI prints a clean upgrade CTA (no traceback) and exits with code 4:

Agent mode requires a paid plan. Upgrade at buildwithtrace.com/pricing to continue — or use ‘ask’ mode (free), or bring your own key.

Run buildwithtrace auth status to check your plan. BYOK does not bypass this gate — bringing your own key skips Trace’s cost cap, but you still need at least the plan that unlocks agent/plan (free accounts can only use ask, even with their own key).Local commands (erc, drc, gerbers, export, convert, index, rules, history) never require auth or a subscription.

Altium conversion: known limitations

The Altium converter handles most real-world projects, but has known edge cases:

Fonts: Custom Altium fonts render as DM Sans. Text sizing may differ slightly.
3D models: Embedded STEP models are referenced but not extracted into separate files.
Custom pad shapes: Arbitrary polygon pads approximated as bounding primitive.
Harness connectors & multi-level bus aliases: Partially supported; deep nesting may lose connectivity.
Expression-based design rules: Converted to comments (KiCad DRC doesn’t support expression rules).
Large files (>200 MB PcbDoc): No size guard — may use significant RAM on memory-constrained machines.
Non-UTF-8 text: Characters not representable in UTF-8 are replaced with �.

If a conversion fails, the error message identifies the exact record or object that caused it. Report issues at support@buildwithtrace.com.

Conversion quality depends on available libraries

When converting .trace_sch → .kicad_sch or .trace_pcb → .kicad_pcb, the converter needs access to KiCad symbol/footprint libraries to produce accurate geometry. Without them:

Symbols get placeholder rectangles with correct pins but approximate dimensions
Footprints get placeholder pads based on pin count but imprecise geometry

The CLI downloads KiCad symbol libraries (~30 MB) to ~/.trace/libraries/ on first use. If the download fails (offline, GitHub unreachable), conversion still works but with reduced visual fidelity.

No 'trace' command (macOS system conflict)

The CLI installs only as buildwithtrace. macOS ships /usr/bin/trace (a kernel tracing tool) — shadowing it would break system debugging. For a shorter alias:

alias bt=buildwithtrace  # add to ~/.zshrc or ~/.bashrc

Credential storage and fallback behavior

The CLI stores auth tokens in your OS keychain:

macOS: Keychain Access (service com.buildwithtrace.cli)
Windows: Credential Manager
Linux: libsecret (GNOME Keyring / KWallet)

Fallback: If the keychain is unavailable (locked, denied, headless server, Docker, missing libsecret), credentials fall back to ~/.config/trace/credentials.json. The CLI does not warn you about this fallback.CI/Docker: Set TRACE_API_TOKEN=trace_pat_xxx as an environment variable instead. This bypasses the keychain entirely.

buildwithtrace auth login opens a browser for OAuth. This fails in:

SSH sessions without X11 forwarding
WSL2 without BROWSER set
Docker containers
Headless CI servers

Workaround: Log in on a machine with a browser, copy the token, and either:

buildwithtrace auth login --token trace_pat_xxx
# or
export TRACE_API_TOKEN=trace_pat_xxx

Corporate proxies and SSL inspection

The CLI respects standard proxy environment variables:

export HTTP_PROXY=http://proxy.corp.com:8080
export HTTPS_PROXY=http://proxy.corp.com:8080

SSL inspection (MITM proxies): If your corporate proxy injects custom CA certificates, you may get SSL errors. Fix:

export SSL_CERT_FILE=/path/to/corporate-ca-bundle.crt
# or
export REQUESTS_CA_BUNDLE=/path/to/corporate-ca-bundle.crt

Buffering proxies: Some proxies buffer HTTP responses. This affects SSE streaming — you’ll see long pauses then bursts of text instead of smooth streaming. The CLI still works correctly; it’s a UX difference.Run buildwithtrace doctor to diagnose connectivity issues — it checks proxy settings and reports them.

CI/CD: ERC/DRC don't need auth or network

buildwithtrace erc and buildwithtrace drc run entirely locally (engine binary + files). They never contact the Trace backend. This means:

Work on forked PRs where secrets aren’t available
Work fully offline
Work behind restrictive firewalls

Requirement: The CI runner needs the Trace engine. On Linux runners (most common), the CLI auto-downloads the AppImage on first use. No manual setup needed:

- name: Install Trace CLI
  run: pip install buildwithtrace
- name: Run ERC
  run: buildwithtrace erc my-schematic.kicad_sch --exit-zero

Exit codes for CI integration

Code	Meaning
`0`	Success
`1`	General failure (conversion error, API error, unexpected exception)
`2`	Authentication required or failed
`5`	Engine binary not found / unavailable
`10`	ERC/DRC found violations (design has issues but the command ran correctly)

Use --exit-zero on erc/drc to always return 0 (useful when you want violations as informational, not blocking).

Don't run two CLI instances on the same project

The CLI has no file locking. Running two buildwithtrace agent or buildwithtrace chat sessions against the same project simultaneously can result in:

Last-write-wins on .trace_sch / .kicad_sch files
Race conditions in the trace→kicad conversion

The desktop app uses hash-based optimistic concurrency + per-file mutexes. The CLI does not (single-process design). If you need parallel AI sessions, use separate project directories or the desktop app.

AI file access is sandboxed

When the AI reads/writes files during chat or agent mode, it’s restricted to:

Only files inside your project directory (path traversal blocked)
Only EDA file types: .trace_sch, .trace_pcb, .kicad_sch, .kicad_pcb, .kicad_sym, .kicad_mod, Altium formats, .svg, .zip, .gbr, .drl, .md, .net

The AI cannot read your .py, .json, .csv, .pdf, .png, or other non-EDA files. If it tries, the CLI blocks it with a security error. This is intentional — the sandbox prevents accidental data exfiltration.

BYOK keys are stored in the OS keychain

buildwithtrace byok set anthropic sk-ant-xxx stores the key in your OS keychain, never in config files or shell history. To rotate: run buildwithtrace byok set again with the new key. To remove: buildwithtrace byok clear.

Offline mode is limited to local commands

Without network, AI commands fail immediately with a clear error. Local commands work fully offline as long as:

The engine binary is already installed (desktop app or KiCad present)
Symbol libraries are already cached (for conversion quality)

Pre-cache everything while online: install the desktop app, then run buildwithtrace convert once to trigger library download.

'history' command requires git

buildwithtrace history uses your system git binary to read the .history/ repository the desktop app maintains. If git is not in your PATH, the command fails with a clear error. Install git from git-scm.com.

Analytics and error reporting opt-out

The CLI sends anonymous usage analytics (PostHog) and crash reports. Analytics is privacy-first: it records only command names, durations, exit codes, and version/OS info — never file contents, file paths, net/component names, or your prompts (a hard PII scrub drops anything that isn’t a short enum/number/boolean). It’s auto-disabled in CI, and source installs (no baked key) never phone home. To disable everywhere:

export TRACE_NO_ANALYTICS=1   # disable PostHog analytics
export DO_NOT_TRACK=1         # cross-tool standard — also disables analytics
export TRACE_NO_REPORTS=1     # disable crash report submission

Add these to your shell profile for permanent opt-out.

Update-available notice

Once per 24h (cached, non-blocking), the CLI checks PyPI for a newer stable release and prints a one-line notice to stderr (never stdout, so piped/--json output is never corrupted):

A new version of buildwithtrace is available: 0.1.0 -> 0.1.1
Upgrade:  pip install -U buildwithtrace   (or: brew upgrade buildwithtrace)

It’s automatically skipped in CI, in JSON/non-TTY contexts, and for buildwithtrace mcp. Disable it entirely with export TRACE_NO_UPDATE_CHECK=1 (or TRACE_NO_ANALYTICS=1).

Network timeouts during AI streaming

AI commands have a 300-second stream timeout. If the model takes longer (very complex tasks) or your connection is slow:

The CLI shows: “Stream timed out after 300s”
Partial output is still visible in your terminal
The conversation may be in an inconsistent state — start a new one rather than --resume

If you’re behind a buffering proxy, the effective timeout may feel shorter because idle time between chunks counts against it.

Where to go next

Command Reference

Every command, subcommand, flag, and exit code.

Bring Your Own Key

Route the AI through your own Anthropic, OpenAI, or Gemini key.

MCP Server & Agent Plugin

npx plugins add buildwithtrace/trace-plugin — skills + MCP for Cursor, Claude, Codex.

Automation & CI/CD

JSON output, exit codes, GitHub Actions, headless auth.

Configuration

config.toml, environment variables, environments, credentials.

Roadmap

What’s shipped, what’s coming, and the doc↔code gaps we’re closing.

TraceRules

Persistent design preferences the AI follows automatically.

Command Line (CLI)

Partner API

Reference

Platforms

Help

What it is

How it fits together

Install

Authenticate

Personal Access Tokens (CI/automation)

Quick start

The command surface at a glance

SDKs (build on Trace from code)

Security

Caveats & FAQ

Local commands require the Trace desktop app (or KiCad)

Where to go next

Command Reference

Bring Your Own Key

MCP Server & Agent Plugin

Automation & CI/CD

Configuration

Roadmap

TraceRules

​What it is

​How it fits together

​Install

​Authenticate

​Personal Access Tokens (CI/automation)

​Quick start

​The command surface at a glance

​SDKs (build on Trace from code)

​Security

​Caveats & FAQ

​Local commands require the Trace desktop app (or KiCad)

​Where to go next

Command Reference

Bring Your Own Key

MCP Server & Agent Plugin

Automation & CI/CD

Configuration

Roadmap

TraceRules

What it is

How it fits together

Install

Authenticate

Personal Access Tokens (CI/automation)

Quick start

The command surface at a glance

SDKs (build on Trace from code)

Security

Caveats & FAQ

Local commands require the Trace desktop app (or KiCad)

Where to go next