TraceDocs
Get Trace

Reference / Trace App CLI

Trace CLI

Use the native CLI bundled with Trace, sign in through the main app, and work safely with saved designs.

Use the CLI from the Trace app

trace-cli is Trace's native C++ command-line executable. Install the Trace desktop app, launch it and sign in to the main app first before using CLI AI or cloud Workspaces commands. The CLI reuses that desktop session; there is no separate CLI login or token setup.

Locate the executable

On macOS, a compatible app installed in /Applications uses:

"/Applications/Trace.app/Contents/MacOS/trace-cli" --version
"/Applications/Trace.app/Contents/MacOS/trace-cli" --help

If Trace is installed elsewhere, use that app's Contents/MacOS/trace-cli. If the executable is missing, check your installed release rather than substituting a different CAD engine.

On Windows, locate trace-cli.exe in the installed Trace application's bin directory. Use the actual path in PowerShell; replace the placeholder:

& "C:\YOUR-TRACE-INSTALLATION\bin\trace-cli.exe" --version
& "C:\YOUR-TRACE-INSTALLATION\bin\trace-cli.exe" --help

On Linux, use the native executable supplied by your installed Trace package. The remaining examples use trace-cli as shorthand for that verified executable. Do not assume the installer added it to PATH; substitute its quoted full path where needed.

Sign in through the main app

trace-cli auth status
trace-cli auth status --json

These commands inspect the existing desktop session, not start sign-in. An expired or unavailable session requires reopening Trace and refreshing sign-in there. Do not pass credentials in command arguments or copy account files between machines. Authentication status can include account and device information; review it before sharing.

Hosted AI requires current account access and available usage, including Ask. See Billing for the authoritative access and charging guide.

Start with a saved design

  1. Save intended editor changes and use a backup or disposable project copy.
  2. Confirm the executable came from your installed Trace app.
  3. Inspect the relevant command's help before using its flags.
  4. Start with a read-only question or local rule check.
  5. Review changed files and run the applicable checks before publishing or fabrication.

Read-only AI question

trace-cli chat --project ./my-board/board.trace_sch --mode ask --model genie-2-flash --message "Explain this design without changes" --format json

Use a saved .trace_sch or .trace_pcb, not a directory. Keep its paired .xo drawing and project dependencies together. A matching .kicad_pro supplies project/library settings; missing settings can change the meaning of checks. --format json emits one chat event per line, not one final JSON object.

Local rule checks

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

These evaluate saved files with the installed native engine and enabled rules; they write reports, not design edits. They are not complete electrical, mechanical or manufacturing certification. See Command reference for exporters and check options.

AI sessions and file safety

The native entry point is chat, with --mode ask, --mode agent or --mode plan. The default is Agent, which can edit files. Specify --mode ask for read-only assistance; choose Agent explicitly only when edits are intended. Plan proposes work rather than granting approval for execution.

Omit --message for an interactive terminal session. A one-shot --message, redirected stdin or --no-interactive does not ask for approvals and declines component previews and deletion requests by default. That is not a general edit prohibition: ordinary Agent writes can still execute. --auto-approve opts into those approvals and is not part of the safe starting workflow. Do not add it to bypass an unexpected refusal.

Hosted AI can receive relevant design context, attachments and tool results, even when file operations execute locally. Local execution is not a promise that design data never leaves your machine.

Avoid concurrent writers to the same project, including an open editor with unsaved buffers. Do not save an older buffer over files changed by a CLI session. Keep native .trace_sch, .trace_pcb and their paired .xo drawing files together; use supported conversion/export rather than renaming extensions.

If a write's response is uncertain, inspect the saved files and the original operation before trying again. Stop or a connection failure does not undo edits that already finished.

Native Workspaces commands

Its explicit workspaces commands use the native Workspaces engine and the desktop account; they are separate from AI chat tools.

Use an absolute, saved .kicad_pro from a registered cloud checkout. Install Trace and sign in to the main app first; refresh the desktop session if needed. Start with reads:

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 --json
trace-cli workspaces branches --project /absolute/design.kicad_pro --json
trace-cli workspaces stashes --project /absolute/design.kicad_pro --json

Status does not claim knowledge of unsaved editor buffers. Save intended work and close affected editors before a mutation needs exclusive native ownership. Do not remove lock files to bypass a refusal.

Before dispatching any supported mutation below, generate a new UUID and retain it with that action's immutable inputs. Replace each request placeholder with its separately retained UUID and pass --request-id explicitly. Do not rely on an automatically generated ID returned only after dispatch: a lost response could also lose the ID needed to observe the original outcome.

trace-cli workspaces commit --project /absolute/design.kicad_pro -m "Saved changes" --request-id COMMIT_REQUEST_UUID --json
trace-cli workspaces push --project /absolute/design.kicad_pro -m "Publish changes" --request-id PUSH_REQUEST_UUID --json
trace-cli workspaces create-branch --project /absolute/design.kicad_pro --name feature --request-id BRANCH_REQUEST_UUID --json
trace-cli workspaces pull --project /absolute/design.kicad_pro --request-id PULL_REQUEST_UUID --json
trace-cli workspaces switch --project /absolute/design.kicad_pro --branch-id BRANCH_UUID --move --request-id SWITCH_REQUEST_UUID --json
trace-cli workspaces restore-stash --project /absolute/design.kicad_pro --stash-id STASH_UUID --request-id RESTORE_REQUEST_UUID --json

Use the exact returned project entries for BRANCH_UUID and STASH_UUID; request UUIDs are the separate IDs you generated and retained before dispatch. Commit saves local history; Push publishes it. Compatible builds support Pull, Switch and conflict-aware restore. --move carries reviewed unpublished changes to the target; --stash parks them on the source for explicit later restoration. They are mutually exclusive. Parking is not proof that a switch finished. The current native Move path refuses unpushed commits; Push on the source first or choose Leave's --stash path. A missing headless checkout owner refuses Pull/Switch rather than proving a GUI open or reload.

Conflicts use conflicts, resolve-conflict and finish with the same original request ID. Inspect their help and current conflict readout before choosing a resolution. Do not assume a conflict-free outcome from an accepted command.

Observe an uncertain native operation

trace-cli workspaces receipt --project /absolute/design.kicad_pro --request-id ORIGINAL_UUID --json
trace-cli workspaces reconcile --project /absolute/design.kicad_pro --request-id ORIGINAL_UUID --json

Receipt reads never retry writes. reconcile observes supported original project-metadata server receipts, such as branch creation and PR mutations, without repeating their writes. It is not a generic recovery command for unknown engine Commit/Push/Pull/Switch/Restore outcomes. Use their matching original-operation conflict/recovery controls, or seek support if unavailable. A missing or unavailable receipt retains uncertainty. Headless completion verifies saved files and does not claim that a GUI editor opened or reloaded.

With compatible native and backend cancellation support, an explicit cancellation can fence the original merge attempt:

trace-cli workspaces cancel-merge --project /absolute/design.kicad_pro --request-id ORIGINAL_UUID --json

This is a mutation: confirm the original request before using it. It does not close the PR or choose conflict winners. It can report verified cancellation or a merge that already completed; a lost reply still needs reconciliation.

Where to go next