Automation & CI/CD

Use the native trace-cli bundled with the Trace app. Start with saved-file checks and exports. For hosted AI or cloud Workspaces, install Trace and sign in through the main app first on the machine and operating-system account running the command. There is no separate CLI login or token setup.

Prepare the runner

1. Install a tested Trace app build with its native executable and libraries.
2. Record the actual executable path and trace-cli --version.
3. Inspect --help for each command and subcommand used by the job.
4. Run a disposable success case, a known rule violation and an execution failure.
5. Record the actual output schema and exit behavior before making the job blocking.

Use the platform-specific executable paths. Examples below use trace-cli as shorthand; substitute the verified full path where needed. Do not assume a hosted runner already has Trace, that it is on PATH, or that an installer includes a command just because current source implements it.

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

See Command reference and Product availability.

Local validation

Read saved native designs with their paired drawings, matching project settings and required libraries. Choose output paths outside your input project when you want an unchanged design inventory:

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

These checks do not technically require hosted AI authentication. They write reports, not intended CAD edits, and evaluate saved files rather than editor buffers. Omit DRC's --save-board for read-only checks.

--exit-code-violations requests nonzero on findings. Without it, a successful process exit alone does not establish a clean report. Keep enabled rules and severity choices explicit, retain reports and treat an execution failure separately from rule violations. Neither outcome is complete engineering certification.

Hosted work uses the main app's session

trace-cli auth status

Status checks the current desktop session and returns nonzero when unavailable. The CLI does not perform unattended sign-in or refresh an expired desktop session. Refresh/sign in in Trace, then check again. A clean ephemeral runner without that session is not ready for hosted steps; use local-only checks there.

Do not export credentials from the desktop store, inject undocumented token variables or copy account files to a runner. Hosted AI also requires account access and available usage, including Ask; see Billing.

Non-interactive does not mean read-only

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

Choose --mode ask for read-only assistance. The chat default is Agent and can edit; explicitly select Agent only for authorized editing work. --message, redirected stdin and --no-interactive decline approval prompts for component previews and deletions by default. They do not prohibit ordinary Agent writes. Do not add --auto-approve to suppress a refusal.

Chat JSON is one event per line; it is not a single report or completion receipt. Do not change a plan or an incomplete response into assumed approval.

Native Workspaces mutation --yes confirms its exact saved-content review, not a stale status result. Without it, interactive commands request confirmation and redirected stdin refuses. Prefer interactive review when a person is authorizing the action. For supported mutations, generate and retain a UUID with the exact inputs before dispatch, then pass --request-id UUID; do not wait for the result to learn an automatically generated ID. Save intended files, close affected editors and do not bypass locks. See Native Workspaces commands.

Exports and batch jobs

• Use separate input copies and fresh, uniquely named output directories.
• Quote paths and handle missing inputs, failures and partial outputs.
• Check Gerber/drill layers, units and filenames before handing files to a manufacturer; do not infer an assembly package from a successful export.
• Reopen converted designs and review connectivity, libraries and geometry.
• Do not allow concurrent editing sessions to write the same project.

trace-cli sch export pdf ./hardware/board.trace_sch --output ./schematic.pdf
trace-cli pcb export gerbers ./hardware/board.trace_pcb --output ./gerbers/
trace-cli pcb export drill ./hardware/board.trace_pcb --output ./drill/

The exact export, conversion, report and JSON flags come from installed help. Pin the tested Trace app build and keep its libraries together; do not mix executables and dependencies from unrelated versions. Run each example only for the intended task, not as an automatic fabrication approval.

Completion and recovery

Record command exit status and typed result separately. An accepted chat turn or cloud request is not proof that the design was saved, published or opened.

If delivery is uncertain, retain the original operation identity and inspect its receipt before retrying. Native workspaces receipt reads the ledger; workspaces reconcile observes supported original project-metadata server receipts without repeating their mutations. It does not settle every unknown engine Commit/Push/Pull/Switch/Restore; use the matching original-operation conflict/recovery path. A missing receipt retains uncertainty. headless_succeeded verifies saved-file effects, not GUI reload. Do not publish again or replay an edit merely because a connection closed.

Treat logs and generated reports as potentially sensitive design data. Apply artifact access controls and retention settings; redact credentials before sharing diagnostics. See Configuration.