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, -VPrint the version banner and exit --jsonEmit JSON instead of formatted text (also via TRACE_JSON=1) --helpShow 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 trial or paid plan.
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, -yAuto-approve all file writes --api-version <v>API version: v3 (default) or 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 questionThe 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 instructionWhat to do (positional, required) --project, -p <dir>Project directory --attach, -a <file>Attach files; repeatable --dry-runPreview 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 requestThe 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 < projec t > [options]
Argument / Option Description projectProject 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 netNet 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
How engine detection works
The CLI searches for the engine binary in this order:
TRACE_ENGINE_PATHTrace 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)$PATHwhich 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 < fil e > [--exit-zero]
Argument / Option Description fileSchematic file (.kicad_sch) --exit-zeroAlways 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 < fil e > [--exit-zero]
Argument / Option Description filePCB file (.kicad_pcb) --exit-zeroAlways exit 0, even with violations
buildwithtrace gerbers Export Gerber + drill files for manufacturing.
buildwithtrace gerbers < fil e > [--output < di r > ]
Argument / Option Description filePCB 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 < subcomman d > < input_fil e > [options]
Subcommand Input Output Options pdf.kicad_sch or .kicad_pcbPDF -o/--output <dir> (default .)svg.kicad_sch or .kicad_pcbSVG -o/--output <dir>netlist.kicad_schNetlist -o/--output <file>, -f/--formatbom.kicad_schBOM CSV -o/--output <file>step.kicad_pcb3D STEP -o/--output <file>pos.kicad_pcbPick-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 statusShow whether the engine is installed and its version (default) installDownload and install the engine updateRe-download the latest engine
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_fil e > [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_fil e > [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_di r > [--output < di r > ]
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 < subcomman d > [options]
Subcommand Description Args component <ref>Show a component’s value, footprint, library, pin count --project/-pnet <name>List all component pins on a net --project/-plistList 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 < subcomman d > [--project < di r > ]
Subcommand Description showPrint the current .trace/rules.md initCreate a starter rules file editOpen 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 < subcomman d > [--project < di r > ]
Subcommand Description Args listList 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 < subcomman d > [options]
search "<query>"Option Description --type, -tFilter: resistor, capacitor, ic, connector, … --package, -pFilter: 0402, SOIC-8, QFP-48, … --in-stockOnly in-stock parts --limit, -l <n>Max results (default 10)
checkOption Description --bom, -b <file>BOM file or project path (required) --distributors, -djlcpcb,lcsc,digikey,mouser--suggest-alternativesSuggest pin-compatible alternatives --format, -ftext, 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 < subcomman d > < projec t > [options]
enrichOption Description --distributors, -dnexar,digikey,mouser--format, -ftext, json, csv
generateOption Description --pricingInclude real-time pricing --optimizeSuggest cost-optimized alternatives --validateCheck parts are available and not EOL --format, -fcsv, 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. Interactive runs prompt for an accept/edit/reject preview and a credit-usage confirmation.
buildwithtrace generate symbol "<component>" [options] buildwithtrace generate footprint "<component>" [options]
Option Description --datasheet, -d <url>Datasheet URL for accurate pinout --datasheet-file, -D <path>Local PDF datasheet (symbol only) --output, -o <dir>Output directory for the generated file --project, -p <dir>Project directory --saveAlso save to your Trace library --publicMake public in the community (requires --save)
buildwithtrace generate symbol "STM32F401" --datasheet https://st.com/.../stm32f401.pdf buildwithtrace generate symbol "TPS563200" -D ~/Downloads/tps563200.pdf -o ./symbols/ buildwithtrace generate footprint "QFN-32 5x5mm 0.5mm pitch"
buildwithtrace dfm Design-for-manufacturing analysis.
buildwithtrace dfm < subcomman d > < projec t > [options]
Subcommand Description autofillRecommend optimal manufacturer parameters from board analysis checkCheck the design against a manufacturer’s capabilities
Option Description --manufacturer, -mpcbway (default), pikkolo, jlcpcb (check only)--format, -ftext, json
buildwithtrace dfm autofill ./my-board/ -m pcbway buildwithtrace dfm check ./my-board/ -m jlcpcb
buildwithtrace order Manufacturing order pipeline.
buildwithtrace order < subcomman d > [args]
Subcommand Args Description submit <project>-m/--manufacturer, --params, --bomPrepare 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>--countryEstimate shipping cost cancel <order_id>— Cancel an order
buildwithtrace order list buildwithtrace order status ord_abc123 buildwithtrace order freight ord_abc123 --country US
Versions, teams, account & sharing 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/--outputRestore 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 statusPlan, usage %, credits, trial state upgradeOpen the billing page in your browser portalOpen the Stripe customer portal
buildwithtrace share 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, --provider (google/github), --no-browserAuthenticate logout— Clear stored credentials status— Account, plan, quota table token— Print the current API token to stdout (for piping)
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, --forceInstall the TraceAI DelphiScript files status— Check whether the bridge is connected serve--api-version, --resumeInteractive chat against the open Altium design review--focus, --api-versionOne-shot review of the open project ask "<question>"--api-versionAsk about the open design dfm--api-versionDFM analysis of the open PCB
buildwithtrace mcp Expose Trace as a Model Context Protocol server. See MCP Server .
Subcommand Options Description serve-p/--projectStart 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>--keyStore 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, and your model provider. Exits non-zero if any check fails. Run it first whenever something misbehaves.
Exit codes Commands use consistent exit codes so you can gate CI on them:
Code Meaning 0Success 1General error 2Not authenticated / auth failed 3File or project not found 4Backend API error 5Engine not installed (run buildwithtrace engine install) 10ERC/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.
