Reference / Trace App CLI

Automation & CI/CD

Run trace-cli checks, exports and other commands in scripts and build pipelines.

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

  1. Install the Trace app on the machine that runs the job. trace-cli and the libraries it needs come with it.
  2. Use the full path to trace-cli in your script, or put it on the machine's PATH with Tools > Install trace-cli Command… in the Trace app. See Find trace-cli.
  3. 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-violations makes a check exit with code 5 when 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 with 0 even 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_pro and rule files with the design. Keep each .trace_sch and .trace_pcb with its matching .xo file.
  • 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 chat never 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-approve accepts previews and deletions instead.
  • Agent mode, the default, can still edit your files. Use --mode ask for answers only.
  • Basic routing and paid advanced layout runs don't start in a script. --allow-route lets it route, and --allow-spend --max-minutes N lets it start paid runs of up to N minutes each.
  • --format json prints 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 --yes it goes ahead without showing you what it will do, so use it only for actions you mean to run unattended.
  • Save a new --request-id for each action. If the job is cut off, check that ID with workspaces receipt before 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 --help with the version notes.