trace-cli runs without a window, so you can put design checks and exports in a script or a build pipeline: run ERC and DRC on every change, export Gerbers for a release, or update a board from its schematic overnight. Coding assistants can use the same commands; see Coding assistants.
Set up the machine
- Install the Trace app on the machine that runs the job.
trace-cliand the libraries it needs come with it. - Use the full path to
trace-cliin your script, or put it on the machine'sPATHwith Tools > Install trace-cli Command… in the Trace app. See Find trace-cli. - Record the version you tested with, and keep that version on the machine:
trace-cli --version
Checks, exports, board updates and conversions don't need a sign-in, so they run on any machine with Trace installed, including a fresh build runner.
Check a design on every change
#!/usr/bin/env bash
set -u
TRACE_CLI="/Applications/Trace.app/Contents/MacOS/trace-cli"
"$TRACE_CLI" sch erc hardware/my-board.trace_sch --output reports/erc.json --format json --exit-code-violations
erc=$?
"$TRACE_CLI" pcb drc hardware/my-board.trace_pcb --output reports/drc.json --format json --exit-code-violations
drc=$?
if [ "$erc" -ne 0 ] || [ "$drc" -ne 0 ]; then
echo "ERC exit code $erc, DRC exit code $drc"
exit 1
fi
--exit-code-violationsmakes a check exit with code5when it finds violations. Any other nonzero code means the check itself couldn't run, for example because a file is missing. Without the option, a check exits with0even when it finds violations. See exit codes.- Keep the reports as build artifacts so you can read the findings.
- The checks use the rules and severities saved in your project, so commit the project's
.kicad_proand rule files with the design. Keep each.trace_schand.trace_pcbwith its matching.xofile. - DRC doesn't change the board unless you add
--save-board.
The project commands do the same from inside the project folder, without naming each file:
cd hardware
"$TRACE_CLI" check --json --exit-code-violations > ../reports/check.json
check runs ERC and DRC and exits with code 5 when either finds errors.
Export files for a release
"$TRACE_CLI" pcb export gerbers hardware/my-board.trace_pcb --output out/fab/ --board-plot-params
"$TRACE_CLI" pcb export drill hardware/my-board.trace_pcb --output out/fab/
"$TRACE_CLI" pcb export pos hardware/my-board.trace_pcb --format csv --output out/fab/positions.csv
"$TRACE_CLI" sch export bom hardware/my-board.trace_sch --output out/bom.csv
"$TRACE_CLI" sch export pdf hardware/my-board.trace_sch --output out/schematic.pdf
Write to a fresh output folder each time, so files from an earlier run can't mix in. Check the layers, drill files and units before you send them to a manufacturer.
trace-cli fab writes Gerbers, drill and position files and a bill of materials in one go and zips them, as the chat's /fab does. Run it in the project folder, with --out to choose the folder.
Commands that use your account
trace-cli chat, basic routing, pcb layout and the Workspaces commands use your Trace account. On a build runner, sign in with an API token from the web dashboard, stored in your build system's secrets and passed in the TRACE_TOKEN environment variable. See Sign in without a browser. Check the sign-in at the start of the job:
"$TRACE_CLI" auth status || { echo "trace-cli is not signed in"; exit 1; }
Never print the token, put it in a script or commit it, and revoke it in the dashboard when you no longer need it.
The assistant in a script
"$TRACE_CLI" chat --project hardware/my-board.trace_sch --mode ask --format json \
--message "List any parts with no footprint, as a table"
- In a script,
trace-cli chatnever stops to ask you anything: part previews and file deletions the assistant asks for are declined, and questions go with the assistant's recommended answer.--auto-approveaccepts previews and deletions instead. - Agent mode, the default, can still edit your files. Use
--mode askfor answers only. - Basic routing and paid advanced layout runs don't start in a script.
--allow-routelets it route, and--allow-spend --max-minutes Nlets it start paid runs of up to N minutes each. --format jsonprints one JSON event per line; the last line sums up the turn.
Workspaces in a script
"$TRACE_CLI" workspaces commit --project "$PROJECT" -m "Nightly update" --request-id "$(uuidgen)" --yes --json
- Without a terminal, a command that changes the project stops unless you add
--yes. With--yesit goes ahead without showing you what it will do, so use it only for actions you mean to run unattended. - Save a new
--request-idfor each action. If the job is cut off, check that ID withworkspaces receiptbefore you run the action again. - The project must not be open in Trace while the job changes it.
Tips
- Work on a checkout or a copy of the project, not on files you have open in Trace.
- Don't run two jobs that write the same project at the same time.
- Reports and exports contain your design. Store them with the same care as the design files.
- If a command behaves differently after you update Trace, compare its
--helpwith the version notes.