Trace CLI Command Reference

This is the complete reference for buildwithtrace (v0.1.0) — the single command the CLI installs. (There’s no trace binary; that name collides with the macOS system /usr/bin/trace. If you want a shorter command, add a shell alias alias trace=buildwithtrace, which shadows the macOS system tool.) Run buildwithtrace <command> --help for inline help on any command.

Global options

These apply to the root command:

Option	Description
`--version`, `-V`	Print the version banner and exit
`--json`	Emit JSON instead of formatted text (also via `TRACE_JSON=1`)
`--help`	Show help for any command or subcommand

When CI is set in the environment, output defaults to JSON automatically and interactive prompts are skipped. See Automation & CI/CD.

AI design commands

These stream from the Trace backend over SSE and execute tool calls locally against your files. They require authentication. Free accounts can use ask; chat/agent/plan require a paid plan, free agent credits, or an active legacy trial.

buildwithtrace chat

Interactive AI design session — the flagship command.

buildwithtrace chat [options]

Option	Description
`--project`, `-p <dir>`	Project directory (defaults to current directory)
`--resume <id>`	Resume a conversation by ID
`--attach`, `-a <file>`	Attach files (images, PDFs); repeatable
`--yes`, `-y`	Auto-approve all file writes
`--api-version <v>`	API version: `latest` (default — newest backend API) or pin `v3`/`v4`

buildwithtrace chat --project ./my-board/
buildwithtrace chat -p ./my-board/ -a datasheet.pdf -a ref-layout.png
buildwithtrace chat --resume cli-chat-ab12cd34ef56

In-session slash commands (model-free, run locally): /help, /clear, /rules, /context.

buildwithtrace ask

Ask a single question. Read-only — no files are modified.

buildwithtrace ask "<question>" [options]

Argument / Option	Description
`question`	The question (positional, required)
`--project`, `-p <dir>`	Project to analyze
`--attach`, `-a <file>`	Attach files; repeatable
`--format`, `-f <type>`	`text` (default), `json`, `markdown`

buildwithtrace ask "What is R14 for?" --project ./my-board/
buildwithtrace ask "What trace width gives 90Ω differential on the inner layers?"

buildwithtrace agent

Execute a single instruction. File writes are auto-approved.

buildwithtrace agent "<instruction>" [options]

Argument / Option	Description
`instruction`	What to do (positional, required)
`--project`, `-p <dir>`	Project directory
`--attach`, `-a <file>`	Attach files; repeatable
`--dry-run`	Preview changes without applying them

buildwithtrace agent "Add test points to all power rails" --project ./my-board/
buildwithtrace agent "Rename net N$3 to USB_DP" --dry-run -p ./my-board/

buildwithtrace plan

Multi-step plan mode: research → questions → plan → execute.

buildwithtrace plan "<request>" [options]

Argument / Option	Description
`request`	The design request (positional, required)
`--project`, `-p <dir>`	Project directory
`--attach`, `-a <file>`	Attach files; repeatable

buildwithtrace plan "Design a 4-layer ESP32-S3 dev board with USB-C and a LiPo charger"

buildwithtrace review

AI design review of a project.

buildwithtrace review <project> [options]

Argument / Option	Description
`project`	Project path to review (positional, required)
`--scope <type>`	`full` (default), `schematic`, `pcb`, `bom`
`--focus <areas>`	Comma-separated: `routing,thermal,impedance,dfm,components,power`
`--format`, `-f <type>`	Output format
`--output`, `-o <file>`	Write the report to a file

buildwithtrace review ./my-board/ --focus thermal,power --output review.md
buildwithtrace review ./my-board/ --scope schematic

buildwithtrace signal

Trace electrical signal paths through schematic connectivity.

buildwithtrace signal [net] [options]

Argument / Option	Description
`net`	Net name to trace (positional, optional if `--component` given)
`--component`, `-c <ref>`	Start from a component (e.g. `U7`)
`--pin <name>`	Pin name/number to start from
`--max-hops <n>`	Max component hops (default `3`)
`--project`, `-p <dir>`	Project directory
`--format`, `-f <type>`	Output format

buildwithtrace signal VCC --project ./my-board/
buildwithtrace signal --component U7 --pin 14 --max-hops 5

Local validation & export

These run on a local engine binary — the same C++ command-line tool (trace-cli) that ships inside the Trace desktop app. On macOS and Windows, the Trace desktop app must be installed (the CLI detects it automatically). On Linux, if the desktop app isn’t installed, the CLI downloads a standalone engine on first use. Manage it with buildwithtrace engine. No account required.

How engine detection works

The CLI searches for the engine binary in this order:

TRACE_ENGINE_PATH environment variable (explicit override)
Trace desktop app — /Applications/Trace.app/Contents/MacOS/trace-cli (macOS), %LOCALAPPDATA%\Programs\Trace\*\bin\trace-cli.exe (Windows), /usr/bin/trace-cli or /opt/trace/bin/trace-cli (Linux)
KiCad — falls back to kicad-cli if Trace isn’t installed (same engine, different branding)
Downloaded standalone — ~/.trace/engine/trace-cli (auto-downloaded on first use if none of the above exist)
$PATH — checks which trace-cli or which kicad-cli

If you have the Trace desktop app installed, you never need to download anything — buildwithtrace erc, buildwithtrace drc, and buildwithtrace gerbers just work immediately.

buildwithtrace erc

Run an Electrical Rule Check on a schematic.

buildwithtrace erc <file> [--exit-zero]

Argument / Option	Description
`file`	Schematic file (`.kicad_sch`)
`--exit-zero`	Always exit `0`, even with violations (useful in CI gates you don’t want to fail)

Exits 10 if violations are found (unless --exit-zero), 5 if the engine isn’t installed.

buildwithtrace drc

Run a Design Rule Check on a PCB.

buildwithtrace drc <file> [--exit-zero]

Argument / Option	Description
`file`	PCB file (`.kicad_pcb`)
`--exit-zero`	Always exit `0`, even with violations

buildwithtrace gerbers

Export Gerber + drill files for manufacturing.

buildwithtrace gerbers <file> [--output <dir>]

Argument / Option	Description
`file`	PCB file (`.kicad_pcb`)
`--output`, `-o <dir>`	Output directory (default `./gerbers/`)

buildwithtrace export

Export design files to other formats. The input file type is auto-detected from its extension.

buildwithtrace export <subcommand> <input_file> [options]

Subcommand	Input	Output	Options
`pdf`	`.kicad_sch` or `.kicad_pcb`	PDF	`-o/--output <dir>` (default `.`)
`svg`	`.kicad_sch` or `.kicad_pcb`	SVG	`-o/--output <dir>`
`netlist`	`.kicad_sch`	Netlist	`-o/--output <file>`, `-f/--format`
`bom`	`.kicad_sch`	BOM CSV	`-o/--output <file>`
`step`	`.kicad_pcb`	3D STEP	`-o/--output <file>`
`pos`	`.kicad_pcb`	Pick-and-place	`-o/--output <dir>`

netlist --format accepts kicad (default), cadstar, orcadpcb2, spice.

buildwithtrace export pdf ./my-board/board.kicad_sch -o ./docs/
buildwithtrace export step ./my-board/board.kicad_pcb -o ./mech/board.step
buildwithtrace export netlist ./my-board/board.kicad_sch --format spice -o sim.cir

buildwithtrace engine

Manage the local engine binary used by ERC/DRC/export.

buildwithtrace engine [status|install|update]

Action	Description
`status`	Show whether the engine is installed and its version (default)
`install`	Download and install the engine
`update`	Re-download the latest engine

Format conversion

Local converters. No account required. Altium parsing uses a verified parser with netlist-driven connectivity for high-fidelity output.

File formats. --format trace writes Trace’s line-oriented text DSL — .trace_sch for schematics, .trace_pcb for PCBs (grammars: trace_sch.ebnf / trace_pcb.ebnf). This is the canonical on-disk format the AI reads and writes, and it round-trips losslessly with KiCad. (trace_json is just an in-memory intermediate the converter passes through — it’s never written to disk by convert.) --format kicad (the default) writes KiCad’s native S-expression .kicad_sch / .kicad_pcb.

buildwithtrace convert schematic

buildwithtrace convert schematic <input_file> [options]

Argument / Option	Description
`input_file`	`.SchDoc`, `.kicad_sch`, or `.trace_sch`
`--output`, `-o <dir>`	Output directory (default `.`)
`--format`, `-f <type>`	`kicad` (default) or `trace`

buildwithtrace convert pcb

buildwithtrace convert pcb <input_file> [options]

Argument / Option	Description
`input_file`	`.PcbDoc`, `.kicad_pcb`, or `.trace_pcb`
`--output`, `-o <dir>`	Output directory
`--format`, `-f <type>`	`kicad` (default) or `trace`

buildwithtrace convert project

Convert an entire Altium project directory (all .SchDoc + .PcbDoc, and writes a .kicad_pro).

buildwithtrace convert project <input_dir> [--output <dir>]

buildwithtrace convert schematic ./Board.SchDoc -o ./out/
buildwithtrace convert pcb ./Board.PcbDoc --format trace
buildwithtrace convert project ./LegacyAltiumProject/ -o ./kicad/

All conversions work out of the box — the local converter is bundled with the CLI. No extra install is required for Trace ↔ KiCad (.trace_sch/.trace_pcb ↔ .kicad_sch/.kicad_pcb) or Altium → KiCad.

Offline EDA helpers

These never touch the network or the AI — pure local parsing. Great for scripts and quick lookups.

buildwithtrace index

Offline component and net lookup across your design files.

buildwithtrace index <subcommand> [options]

Subcommand	Description	Args
`component <ref>`	Show a component’s value, footprint, library, pin count	`--project/-p`
`net <name>`	List all component pins on a net	`--project/-p`
`list`	List every indexed component	`--project/-p`

buildwithtrace index component U7
buildwithtrace index net VCC --project ./my-board/
buildwithtrace index list

buildwithtrace rules

Manage .trace/rules.md — persistent design preferences the AI reads at the start of every conversation. See TraceRules.

buildwithtrace rules <subcommand> [--project <dir>]

Subcommand	Description
`show`	Print the current `.trace/rules.md`
`init`	Create a starter rules file
`edit`	Open the rules file in `$EDITOR`
`set "<line>"`	Append a single rule line

buildwithtrace rules init
buildwithtrace rules set "Always use 0402 passives unless I say otherwise"
buildwithtrace rules show

buildwithtrace history

Read-only browser for the desktop app’s .history/ autosave repository. The CLI never writes to it (to avoid conflicting with the desktop app).

buildwithtrace history <subcommand> [--project <dir>]

Subcommand	Description	Args
`list`	List recent autosave snapshots	`--limit/-n` (default `30`)
`show <commit>`	Show a snapshot’s diff stat	—

buildwithtrace history list -n 50
buildwithtrace history show a1b2c3d

Components, BOM & manufacturing

Backend commands (require auth).

buildwithtrace components

buildwithtrace components <subcommand> [options]

search "<query>" — search distributors (Nexar/DigiKey/Mouser):

Option	Description
`--type`, `-t`	Filter: `resistor`, `capacitor`, `ic`, `connector`, …
`--package`, `-p`	Filter: `0402`, `SOIC-8`, `QFP-48`, …
`--in-stock`	Only in-stock parts
`--limit`, `-l <n>`	Max results (default `10`)

check — validate a BOM against distributor stock:

Option	Description
`--bom`, `-b <file>`	BOM file or project path (required)
`--distributors`, `-d`	`jlcpcb,lcsc,digikey,mouser`
`--suggest-alternatives`	Suggest pin-compatible alternatives
`--format`, `-f`	`text`, `json`, `csv`

buildwithtrace components search "LDO 3.3V 500mA" --package SOT-223 --in-stock
buildwithtrace components check --bom ./my-board/ -d jlcpcb,digikey --suggest-alternatives

buildwithtrace bom

buildwithtrace bom <subcommand> <project> [options]

enrich — fill in missing MPNs from distributors:

Option	Description
`--distributors`, `-d`	`nexar,digikey,mouser`
`--format`, `-f`	`text`, `json`, `csv`

generate — full BOM generation:

Option	Description
`--pricing`	Include real-time pricing
`--optimize`	Suggest cost-optimized alternatives
`--validate`	Check parts are available and not EOL
`--format`, `-f`	`csv`, `json`, `html`
`--output`, `-o <file>`	Write the BOM to a file

buildwithtrace bom enrich ./my-board/ -d nexar
buildwithtrace bom generate ./my-board/ --pricing --validate -o bom.csv

buildwithtrace generate

Generate KiCad symbols and footprints with AI. The component is generated server-side and the file is written to your project (<name>.kicad_sym / <name>.kicad_mod). Interactive runs ask for a credit-usage confirmation first.

buildwithtrace generate symbol "<component>" [options]
buildwithtrace generate footprint "<component>" [options]

Option	Description
`--datasheet`, `-d <url>`	Datasheet URL for accurate pinout. If omitted, the part number is searched.
`--output`, `-o <dir>`	Output directory for the generated file
`--project`, `-p <dir>`	Project directory
`--save`	Also save to your Trace library
`--public`	Make public in the community (requires `--save`)

--datasheet-file (local PDF) is deprecated and not used by generation — pass a --datasheet <url>, or omit it and the part number will be searched for a datasheet automatically.

buildwithtrace generate symbol "STM32F401" --datasheet https://st.com/.../stm32f401.pdf
buildwithtrace generate symbol "TPS563200" -o ./symbols/
buildwithtrace generate footprint "QFN-32 5x5mm 0.5mm pitch"

Datasheet questions (“what’s the pinout of the STM32F401?”) go through buildwithtrace ask or agent — the AI fetches and parses the datasheet itself (URL, part number, or an attached PDF) and answers with just the relevant section.

buildwithtrace dfm

Design-for-manufacturing analysis.

buildwithtrace dfm <subcommand> <project> [options]

Subcommand	Description
`autofill`	Recommend optimal manufacturer parameters from board analysis
`check`	Check the design against a manufacturer’s capabilities

Option	Description
`--manufacturer`, `-m`	`pcbway` (default), `pikkolo`, `jlcpcb` (`check` only)
`--format`, `-f`	`text`, `json`

buildwithtrace dfm autofill ./my-board/ -m pcbway
buildwithtrace dfm check ./my-board/ -m jlcpcb

buildwithtrace order

Manufacturing order pipeline.

buildwithtrace order <subcommand> [args]

Subcommand	Args	Description
`submit <project>`	`-m/--manufacturer`, `--params`, `--bom`	Prepare an order (`pcbway`/`pikkolo`)
`list`	—	List your PCB orders
`status <order_id>`	—	Live manufacturing status
`checkout <order_id>`	—	Create a payment session and open the browser
`freight <order_id>`	`--country`	Estimate shipping cost
`cancel <order_id>`	—	Cancel an order

buildwithtrace order list
buildwithtrace order status ord_abc123
buildwithtrace order freight ord_abc123 --country US

Backend commands (require auth).

buildwithtrace versions

Schematic version snapshots (full file content, stored server-side).

Subcommand	Args	Description
`list <project>`	`-n/--limit` (default `20`)	List saved versions
`save [name]`	`-p/--project` (required)	Save the current schematic as a version
`restore <version_id>`	`-o/--output`	Restore a version (overwrites original unless `-o`)

buildwithtrace versions save "before routing" --project ./my-board/board.kicad_sch
buildwithtrace versions list ./my-board/board.kicad_sch
buildwithtrace versions restore 1a2b3c4d -o ./recovered.kicad_sch

buildwithtrace teams

Subcommand	Args	Description
`list`	—	List your teams
`create <name>`	—	Create a team
`invite <team_id> <email>`	`-r/--role` (`member`/`admin`)	Invite a member

buildwithtrace billing

Subcommand	Description
`status`	Plan, usage %, credits, trial state
`upgrade`	Open the billing page in your browser
`portal`	Open the Stripe customer portal

Shareable conversation links.

Subcommand	Args	Description
`create <conversation_id>`	—	Create a public share link
`list`	—	List your share links and view counts
`revoke <token>`	—	Revoke a link

buildwithtrace auth

Subcommand	Options	Description
`login`	`--email/-e`, `--password`, `--token/-t`, `--no-browser`	Authenticate. Default opens the browser to the login page (provider chosen in-browser, captcha solved there) and waits on a loopback callback. `--no-browser` prints the URL; `--token`/`--email`+`--password` are headless fallbacks. (`--provider` is deprecated and ignored.)
`logout`	—	Clear stored credentials
`status`	—	Account, plan, quota table
`token`	`--create`, `--name <n>`, `--scope <s>` (repeatable), `--expires-days <n>`, `--list`, `--revoke <id>`	With no flags: print the current session token to stdout (for piping). `--create` mints a long-lived Personal Access Token (`trace_pat_...`, shown once); `--list`/`--revoke` manage them. Scopes: `mcp:all` (default) or `partner:read`.

buildwithtrace auth token --create --name ci-bot --expires-days 90
buildwithtrace auth token --list
buildwithtrace auth token --revoke 1a2b3c4d

Token management (create/list/revoke) requires an interactive login session — a PAT can’t manage tokens (enforced server-side, so a leaked PAT can’t mint more or revoke yours). PATs can also be created in the dashboard (Settings → Developer, with a scope + expiry picker). buildwithtrace whoami (top-level) prints the current user.

Integrations

buildwithtrace altium

Live bridge to a running Altium Designer instance (file-based IPC). Run buildwithtrace altium install-scripts first, then start StartTraceServer from the TraceAI script inside Altium.

Subcommand	Options	Description
`install-scripts`	`--dest`, `--force`	Install the TraceAI DelphiScript files
`status`	—	Check whether the bridge is connected
`serve`	`--api-version`, `--resume`	Interactive chat against the open Altium design
`review`	`--focus`, `--api-version`	One-shot review of the open project
`ask "<question>"`	`--api-version`	Ask about the open design
`dfm`	`--api-version`	DFM analysis of the open PCB

buildwithtrace mcp

Expose Trace as a Model Context Protocol server. See MCP Server.

Subcommand	Options	Description
`serve`	`-p/--project`	Start the stdio MCP server (requires auth)
`tools`	—	List the available MCP tools

buildwithtrace byok

Bring your own LLM key. See Bring Your Own Key.

Subcommand	Args	Description
`set <provider>`	`--key`	Store a provider key and switch to it
`use <provider>`	—	Switch active provider (`anthropic`/`openai`/`gemini`/`trace`)
`model <model_id>`	—	Set the model ID for your BYOK provider
`status`	—	Show the active provider and key state
`clear <provider>`	—	Remove a stored key

Configuration & diagnostics

buildwithtrace config

Subcommand	Args	Description
`set <key> <value>`	—	Set a config value (e.g. `env`, `output.format`)
`get <key>`	—	Read a config value
`list`	—	Show all config plus effective env/backend URL

backend is an alias for env. See Configuration.

buildwithtrace doctor

Diagnoses API connectivity, authentication, the engine binary, Python version, installed copies, and your model provider. Exits non-zero if any check fails. Run it first whenever something misbehaves. The CLI can be installed through several channels (pip, Homebrew, npm, or the curl installer). doctor reports the running copy’s version and install origin, lists every buildwithtrace executable found on your PATH, and warns when multiple distinct installs coexist — PATH order decides which one runs, so keep one channel and uninstall the rest. buildwithtrace --version also shows the install origin, e.g. v0.1.4 (homebrew).

buildwithtrace doctor

Exit codes

Commands use consistent exit codes so you can gate CI on them:

Code	Meaning
`0`	Success
`1`	General error
`2`	Not authenticated / auth failed
`3`	File or project not found
`4`	Backend API error, or the mode isn’t permitted for your plan (e.g. `agent`/`plan` on the free plan)
`5`	Engine not installed (run `buildwithtrace engine install`)
`10`	ERC/DRC violations found

In CI, pass --exit-zero to buildwithtrace erc/buildwithtrace drc when you want to collect results without failing the job, and omit it when violations should block the pipeline.

​Global options

​AI design commands

​buildwithtrace chat

​buildwithtrace ask

​buildwithtrace agent

​buildwithtrace plan

​buildwithtrace review

​buildwithtrace signal

​Local validation & export

​buildwithtrace erc

​buildwithtrace drc

​buildwithtrace gerbers

​buildwithtrace export

​buildwithtrace engine

​Format conversion

​buildwithtrace convert schematic

​buildwithtrace convert pcb

​buildwithtrace convert project

​Offline EDA helpers

​buildwithtrace index

​buildwithtrace rules

​buildwithtrace history

​Components, BOM & manufacturing

​buildwithtrace components

​buildwithtrace bom

​buildwithtrace generate

​buildwithtrace dfm

​buildwithtrace order

​Versions, teams, account & sharing

​buildwithtrace versions

​buildwithtrace teams

​buildwithtrace billing

​buildwithtrace share

​buildwithtrace auth

​Integrations

​buildwithtrace altium

​buildwithtrace mcp

​buildwithtrace byok

​Configuration & diagnostics

​buildwithtrace config

​buildwithtrace doctor

​Exit codes

Global options

AI design commands

buildwithtrace chat

buildwithtrace ask

buildwithtrace agent

buildwithtrace plan

buildwithtrace review

buildwithtrace signal

Local validation & export

buildwithtrace erc

buildwithtrace drc

buildwithtrace gerbers

buildwithtrace export

buildwithtrace engine

Format conversion

buildwithtrace convert schematic

buildwithtrace convert pcb

buildwithtrace convert project

Offline EDA helpers

buildwithtrace index

buildwithtrace rules

buildwithtrace history

Components, BOM & manufacturing

buildwithtrace components

buildwithtrace bom

buildwithtrace generate

buildwithtrace dfm

buildwithtrace order

Versions, teams, account & sharing

buildwithtrace versions

buildwithtrace teams

buildwithtrace billing

buildwithtrace share

buildwithtrace auth

Integrations

buildwithtrace altium

buildwithtrace mcp

buildwithtrace byok

Configuration & diagnostics

buildwithtrace config

buildwithtrace doctor

Exit codes