Trace CLI — Automation & CI/CD

The CLI is built to run unattended. Local validation needs no account; AI commands need a token. This page covers headless auth, exit codes, JSON output, and ready-to-use CI recipes.

Headless authentication

In non-interactive environments, authenticate with a token instead of the browser. Two options:

Dashboard (recommended for CI): Go to buildwithtrace.com/dashboard/settings > Developer > Create Token. This generates a long-lived Personal Access Token (trace_pat_...), with a scope (mcp:all default / partner:read) + expiry picker. Shown once — copy it.
CLI: Run buildwithtrace auth login on a machine with a browser, then buildwithtrace auth token --create --name ci-bot to mint a PAT (or plain buildwithtrace auth token to print the shorter-lived session token).

export TRACE_API_TOKEN=trace_pat_xxx

Creating/listing/revoking tokens needs an interactive login session — a PAT can’t manage tokens. Mint PATs on your laptop (or the dashboard) and inject them into CI as a secret.

When TRACE_API_TOKEN is set, every command uses it automatically — no buildwithtrace auth login needed. Local-only commands (erc, drc, gerbers, export, convert, index) don’t need a token at all.

Non-interactive behavior

When CI is set (GitHub Actions, GitLab CI, etc.) or TRACE_NO_INTERACTIVE=1 is set:

Output defaults to JSON.
Confirmation prompts (like the symbol-generation credit prompt) are skipped.
Preview/accept-edit-reject loops auto-accept.

You can also force JSON per-invocation with the global --json flag or TRACE_JSON=1.

Exit codes

Gate your pipeline on these:

Code	Meaning
`0`	Success
`1`	General error
`2`	Not authenticated / auth failed
`3`	File or project not found
`4`	Backend API error, or the mode isn’t permitted for your plan (`agent`/`plan` on free)
`5`	Engine not installed
`10`	ERC/DRC violations found

buildwithtrace erc ./hardware/board.kicad_sch          # exits 10 if violations
buildwithtrace erc ./hardware/board.kicad_sch --exit-zero   # always exits 0 (collect, don't block)

GitHub Actions

Use the official action. It installs Python if needed, installs the CLI, wires TRACE_API_TOKEN, and runs buildwithtrace doctor.

- uses: buildwithtrace/github-action@v1
  with:
    token: ${{ secrets.TRACE_API_TOKEN }}   # optional — only needed for AI commands
    version: latest                          # or pin e.g. '0.1.0'

Supported runners: ubuntu-* and macos-*. Windows runners are not yet supported. Add TRACE_API_TOKEN as a repository secret under Settings → Secrets and variables → Actions.

Validate on every PR

name: PCB Validation
on: pull_request

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: buildwithtrace/github-action@v1

      - name: ERC
        run: buildwithtrace erc ./hardware/board.kicad_sch

      - name: DRC
        run: buildwithtrace drc ./hardware/board.kicad_pcb

ERC/DRC run on the bundled engine and need no token — these jobs work on forked PRs where secrets aren’t available.

AI design review on PRs

name: AI Design Review
on: pull_request

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: buildwithtrace/github-action@v1
        with:
          token: ${{ secrets.TRACE_API_TOKEN }}

      - name: Review
        run: buildwithtrace review ./hardware/ --focus "power,manufacturability" --format markdown --output review.md

      - name: Comment on PR
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          path: review.md

Generate Gerbers on release

name: Manufacturing Files
on:
  release:
    types: [published]

jobs:
  gerbers:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: buildwithtrace/github-action@v1

      - name: Gerbers
        run: buildwithtrace gerbers ./hardware/board.kicad_pcb --output ./fab/

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: gerbers-${{ github.ref_name }}
          path: ./fab/

Matrix across multiple boards

jobs:
  validate:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        board:
          - hardware/main/main.kicad_pcb
          - hardware/power/power.kicad_pcb
    steps:
      - uses: actions/checkout@v4
      - uses: buildwithtrace/github-action@v1
      - run: buildwithtrace drc ${{ matrix.board }}

Other CI systems

Any runner with Python 3.10+ works:

pip install buildwithtrace
export TRACE_API_TOKEN=$CI_TRACE_TOKEN
buildwithtrace doctor
buildwithtrace erc ./hardware/board.kicad_sch

Scripting recipes

Batch convert a folder of Altium projects

for dir in legacy/*/; do
  buildwithtrace convert project "$dir" --output "kicad/$(basename "$dir")"
done

Export manufacturing files for every board

for pcb in hardware/**/*.kicad_pcb; do
  out="fab/$(basename "${pcb%.kicad_pcb}")"
  buildwithtrace gerbers "$pcb" --output "$out"
  buildwithtrace export step "$pcb" --output "$out/board.step"
done

Pipe the API token to another tool

MY_TOKEN=$(buildwithtrace auth token)
curl -H "Authorization: Bearer $MY_TOKEN" https://api.buildwithtrace.com/api/v3/user/profile

Consume JSON output

buildwithtrace ask "List the power rails in this design" --project ./board/ --format json | jq '.'

Environment variables for CI

Variable	Use
`TRACE_API_TOKEN`	Auth token (skips `buildwithtrace auth login`)
`CI`	Auto-enables JSON output + non-interactive mode
`TRACE_NO_INTERACTIVE`	Force non-interactive mode
`TRACE_JSON`	Force JSON output
`TRACE_NO_ANALYTICS` / `DO_NOT_TRACK`	Disable usage analytics (also auto-off under `CI`)
`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY`	BYOK keys for the `byok` CLI (see BYOK)
`TRACE_LLM_PROVIDER` / `TRACE_LLM_API_KEY` / `TRACE_LLM_MODEL`	BYOK routing for the SDKs (set once via env)

See the full list on the Configuration page.

Command Line (CLI)

Partner API

Reference

Platforms

Help

Automation & CI/CD

Headless authentication

Non-interactive behavior

Exit codes

GitHub Actions

Validate on every PR

AI design review on PRs

Generate Gerbers on release

Matrix across multiple boards

Other CI systems

Scripting recipes

Batch convert a folder of Altium projects

Export manufacturing files for every board

Pipe the API token to another tool

Consume JSON output

Environment variables for CI

​Headless authentication

​Non-interactive behavior

​Exit codes

​GitHub Actions

​Validate on every PR

​AI design review on PRs

​Generate Gerbers on release

​Matrix across multiple boards

​Other CI systems

​Scripting recipes

​Batch convert a folder of Altium projects

​Export manufacturing files for every board

​Pipe the API token to another tool

​Consume JSON output

​Environment variables for CI

Headless authentication

Non-interactive behavior

Exit codes

GitHub Actions

Validate on every PR

AI design review on PRs

Generate Gerbers on release

Matrix across multiple boards

Other CI systems

Scripting recipes

Batch convert a folder of Altium projects

Export manufacturing files for every board

Pipe the API token to another tool

Consume JSON output

Environment variables for CI