TraceDocs
Get Trace

Reference / Trace App CLI

CLI Command Reference

Native Trace command families, saved-file checks, exporters and safe chat options.

Use the native trace-cli supplied with the Trace app. Install Trace and sign in to the main app first for AI and cloud Workspaces commands. There is no separate CLI login or credential argument. See executable paths and prerequisites.

Verify your command surface

trace-cli --version
trace-cli --help
trace-cli chat --help
trace-cli sch erc --help
trace-cli pcb drc --help

Examples use trace-cli as shorthand for the verified installed executable; substitute its full path if it is not on PATH. A newer service or a command in source does not add it to an older installer. Use each subcommand's help for its accepted inputs, flags and output path type.

AI chat

The root command is chat; Ask, Agent and Plan are modes, not separate root commands. Hosted AI needs the main app's current session, account access and available usage, including Ask. See Billing.

trace-cli chat --project ./my-board/board.trace_sch --mode ask --model genie-2-flash --message "Explain this design without changes" --format json
  • --project PATH: a saved .trace_sch or .trace_pcb, not a directory.
  • --mode ask|agent|plan: Ask is read-only; Agent is the default and can edit. Choose Agent explicitly only for intended edits. A plan is not execution approval.
  • --model: gpt-astra, gpt-sol, genie-2-flash or genie-2, corresponding to GPT Astra, GPT Sol, Trace Genie 2.0 Flash and Trace Genie 2.0. Omission uses the service default.
  • --message TEXT or -m TEXT: one turn and exit. Omit it for an interactive terminal session.
  • --format text|json: text or one JSON event per line.
  • --conversation ID: continue the intended existing conversation; not a retry mechanism for an uncertain write.
  • --no-interactive: never ask stdin for approvals; component previews and deletions are declined. It does not prevent ordinary Agent file writes.
  • --auto-approve: explicitly approve component previews and deletions without asking. Leave it out of the safe starting workflow.

A one-shot message or redirected stdin also declines approval prompts by default. Do not confuse that behavior with Ask's read-only mode. Hosted AI can receive relevant design context even when tools execute locally.

Local validation

Local checks read saved designs, not unsaved editor buffers. They do not require an AI sign-in; the compatible installed app and libraries are still required. Keep native files, their .xo drawings and project settings together.

trace-cli sch erc ./my-board/board.trace_sch --output ./erc-report.json --format json --exit-code-violations
trace-cli pcb drc ./my-board/board.trace_pcb --output ./drc-report.json --format json --exit-code-violations

Both commands accept --format json|report for the report file. --output selects that file. --exit-code-violations requests a nonzero exit when findings exist; without it, exit zero alone does not mean a clean check. Severity flags select reported errors, warnings and exclusions. Inspect the enabled rules and actual report, not just the exit status.

DRC can additionally offer --schematic-parity, --refill-zones and --save-board. The latter writes the board and requires --refill-zones; omit it for a read-only design check. A report writes an output artifact but does not certify electrical, mechanical or manufacturing fitness.

Exports

Native exporter families include:

  • sch export: pdf, svg, dxf, hpgl, ps, netlist and bom.
  • pcb export: gerbers, drill, pdf, svg, dxf, pos, step, glb, vrml, ipc2581, ipcd356, odb, gencad, hpgl, ps and stats.
  • sym export svg and fp export svg: library graphics.

These are a selection, not an exhaustive list for every installed release. Use each exporter's help: output paths can be files or directories, and flags such as layers, units or variants are not interchangeable.

trace-cli sch export pdf ./my-board/board.trace_sch --output ./schematic.pdf
trace-cli sch export netlist ./my-board/board.trace_sch --output ./board.net --format kicadsexpr
trace-cli pcb export gerbers ./my-board/board.trace_pcb --output ./gerbers/
trace-cli pcb export drill ./my-board/board.trace_pcb --output ./drill/

Use fresh output locations. Check every required layer, drill file, unit and filename before fabrication. A Gerber export is not an assembly package; a SPICE netlist export is not a completed simulation or a PASS.

Conversion and board changes

The native tree also includes sch convert, pcb convert, pcb import and board-processing commands such as pcb refill, pcb repair and pcb layout. They are not all read-only or offline. Inspect installed help and the relevant workflow before use, especially for paid/global placement and routing.

Convert a disposable copy into a separate output location, then reopen it and review hierarchy, connectivity, libraries, footprints and drawings. Do not rename extensions or assume every construct survives conversion.

Native Workspaces

The separate workspaces tree offers saved-file reads and explicitly reviewed actions in compatible builds. Its project is an absolute saved .kicad_pro in a registered cloud checkout, except Add, which starts from a saved local project. Save intended changes and close affected editors before an action requires exclusive ownership.

trace-cli workspaces status --project /absolute/design.kicad_pro --json
trace-cli workspaces review --project /absolute/design.kicad_pro --json
trace-cli workspaces changes --project /absolute/design.kicad_pro --limit 32 --offset 0 --json
trace-cli workspaces receipt --project /absolute/design.kicad_pro --request-id ORIGINAL_UUID --json

Check workspaces --help and the exact action's help. Mutation --yes confirms the owning native review, not a cached “clean” label; prefer the interactive confirmation. For each supported mutation, generate and retain its UUID and inputs before dispatch, then pass --request-id UUID explicitly. receipt observes that original ID. reconcile reads supported project-metadata server receipts only; unknown engine commands need their matching recovery flow. Neither receipt read replays a write. Use the native Workspaces guide for Commit/Push/Pull, switch/stash and original-operation recovery.

Account and version

trace-cli auth status
trace-cli auth status --json
trace-cli version --format plain
trace-cli version --format commit

auth status inspects the main app's session and returns nonzero if it is unavailable. Refresh or sign in in Trace; there is no auth login command. Account-status JSON includes personal/device information, not a credential to copy. version reports the executable's build, not service deployment or feature availability.

Rules and configuration

Edit personal preferences in .trace/rules.md through the main app or your text editor. There is no native rules command; see TraceRules. Configuration explains session handling and explicit per-command options. Native MCP-server and BYOK command setup is not documented as an available command surface.

Exit codes and output

Chat uses an event stream, Workspaces --json returns one structured result, and ERC/DRC --format json writes a report. They are different contracts. Test a disposable success, a known finding and an execution failure before making a command a blocking job.

Record exit status and typed completion separately. An accepted request, run ID or successful receipt read does not prove a write, Push or checkout completed. Preserve an uncertain operation's original identity; never replay it automatically with new inputs or a new request ID.