TraceDocs
Get Trace

Reference / Trace App CLI

CLI Configuration

Use the installed native executable, the main app's session and explicit command options.

The native trace-cli comes from the Trace desktop app. Install Trace, launch it and sign in to the main app first for AI and cloud Workspaces commands. The CLI reads that existing desktop session and project settings. It does not require a separate account token or CLI configuration file.

Select the installed executable

trace-cli --version
trace-cli --help
trace-cli chat --help

Use the executable supplied with your installed Trace app, not a replacement engine. See CLI setup for macOS and Windows paths. If it is not on PATH, substitute its quoted absolute path.

Check each subcommand's help before copying flags. A feature in current source does not guarantee that your downloaded installer contains it.

Desktop session

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

The native CLI restores the desktop's current session without starting a browser login or rotating the shared refresh token. An expired session is unavailable: reopen Trace and refresh/sign in there, then check status again. There is no auth login command.

Keep the app and CLI under the same operating-system account. Do not copy credential stores, pass bearer tokens in arguments or edit account files to bypass sign-in. Status JSON includes account/device details; inspect it privately and redact it before sharing.

Hosted AI also needs current account access and available usage, including Ask. Cloud project permissions are separate from successful sign-in. See Billing.

Saved project context

For chat, --project selects a saved .trace_sch or .trace_pcb file, not a directory. Keep its .xo drawing and required libraries beside the design. A matching .kicad_pro supplies project settings; missing settings can cause checks to use defaults.

For workspaces, use an absolute saved .kicad_pro from the registered cloud checkout. Add is the separate action for a saved local source. The native CLI reads the desktop registry; a directory or unrelated local file is not a substitute for a registered working copy.

Personal .trace/rules.md preferences can accompany new chat requests. .trace/context.md contains shared project notes. Neither file grants permissions or replaces a native operation review. See TraceRules.

Per-command options

  • Choose chat --mode ask for read-only assistance. Agent is the default and can edit; select it explicitly only when edits are intended.
  • chat --model accepts gpt-astra, gpt-sol, genie-2-flash or genie-2. Omit it to use the service default.
  • chat --format json emits JSON events, one per line.
  • Workspaces uses --json for a single structured result.
  • ERC/DRC use --format json --output FILE for a report file.
  • --no-interactive suppresses chat approval prompts; it is not a read-only mode. Ordinary Agent writes remain possible.
  • Workspaces --yes explicitly confirms the exact native review. It is not a chat flag or a way to repair denied authority.

A generic CI environment setting does not establish these options or turn an editing session into read-only work. Use the installed command's explicit flags and test its result format.

Service and data boundaries

Use the normal service shipped with the Trace app. Do not change servers to work around a refusal or retry an uncertain operation against another service: the original request and desktop identity belong to their original context.

Local ERC/DRC and exports do not technically need authentication; they still require the installed native dependencies and write reports/output artifacts. Hosted chat can send relevant design context and tool results to the service. Local tool execution is not a guarantee that design content stays offline.

There is no documented native BYOK configuration command. Use BYOK availability for the current boundary and Automation & CI/CD for saved-file automation.