> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithtrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Automation & CI/CD

> Run Trace headless — validate PCBs in CI, generate Gerbers on release, script batch jobs, and consume JSON output.

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](https://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.
2. **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).

```bash theme={null}
export TRACE_API_TOKEN=trace_pat_xxx
```

<Note>
  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.
</Note>

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                                                              |

```bash theme={null}
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`.

```yaml theme={null}
- 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'
```

<Note>
  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**.
</Note>

### Validate on every PR

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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:

```bash theme={null}
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

```bash theme={null}
for dir in legacy/*/; do
  buildwithtrace convert project "$dir" --output "kicad/$(basename "$dir")"
done
```

### Export manufacturing files for every board

```bash theme={null}
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

```bash theme={null}
MY_TOKEN=$(buildwithtrace auth token)
curl -H "Authorization: Bearer $MY_TOKEN" https://api.buildwithtrace.com/api/v3/user/profile
```

### Consume JSON output

```bash theme={null}
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](/resources/cli-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](/resources/cli-config) page.