Skip to main content
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:
  1. Dashboard (recommended for CI): Go to buildwithtrace.com/dashboard/settings > Developer > Create Token. This generates a long-lived Personal Access Token.
  2. CLI: Run buildwithtrace auth login on a machine with a browser, then buildwithtrace auth token to print your session token (shorter-lived).
export TRACE_API_TOKEN=trc_xxx
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:
CodeMeaning
0Success
1General error
2Not authenticated / auth failed
3File or project not found
4Backend API error
5Engine not installed
10ERC/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/cli/github-action@main
  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/cli/github-action@main

      - 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/cli/github-action@main
        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/cli/github-action@main

      - 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/cli/github-action@main
      - 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

VariableUse
TRACE_API_TOKENAuth token (skips buildwithtrace auth login)
CIAuto-enables JSON output + non-interactive mode
TRACE_NO_INTERACTIVEForce non-interactive mode
TRACE_JSONForce JSON output
TRACE_NO_ANALYTICSDisable PostHog usage analytics
ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEYBYOK keys (see BYOK)
See the full list on the Configuration page.