> ## 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.

# CLI Command Reference

> Every Trace CLI command, subcommand, flag, and exit code — generated from the shipping source.

This is the complete reference for `buildwithtrace` (`v0.1.0`) — the single command the CLI installs. (There's no `trace` binary; that name collides with the macOS system `/usr/bin/trace`. If you want a shorter command, add a shell alias `alias trace=buildwithtrace`, which shadows the macOS system tool.) Run `buildwithtrace <command> --help` for inline help on any command.

## Global options

These apply to the root command:

| Option            | Description                                                   |
| ----------------- | ------------------------------------------------------------- |
| `--version`, `-V` | Print the version banner and exit                             |
| `--json`          | Emit JSON instead of formatted text (also via `TRACE_JSON=1`) |
| `--help`          | Show help for any command or subcommand                       |

<Note>
  When `CI` is set in the environment, output defaults to JSON automatically and interactive prompts are skipped. See [Automation & CI/CD](/resources/cli-automation).
</Note>

## AI design commands

These stream from the Trace backend over SSE and execute tool calls locally against your files. They require authentication. Free accounts can use `ask`; `chat`/`agent`/`plan` require a paid plan, free agent credits, or an active legacy trial.

### buildwithtrace chat

Interactive AI design session — the flagship command.

```bash theme={null}
buildwithtrace chat [options]
```

| Option                  | Description                                                           |
| ----------------------- | --------------------------------------------------------------------- |
| `--project`, `-p <dir>` | Project directory (defaults to current directory)                     |
| `--resume <id>`         | Resume a conversation by ID                                           |
| `--attach`, `-a <file>` | Attach files (images, PDFs); repeatable                               |
| `--yes`, `-y`           | Auto-approve all file writes                                          |
| `--api-version <v>`     | API version: `latest` (default — newest backend API) or pin `v3`/`v4` |

```bash theme={null}
buildwithtrace chat --project ./my-board/
buildwithtrace chat -p ./my-board/ -a datasheet.pdf -a ref-layout.png
buildwithtrace chat --resume cli-chat-ab12cd34ef56
```

In-session slash commands (model-free, run locally): `/help`, `/clear`, `/rules`, `/context`.

### buildwithtrace ask

Ask a single question. Read-only — no files are modified.

```bash theme={null}
buildwithtrace ask "<question>" [options]
```

| Argument / Option       | Description                          |
| ----------------------- | ------------------------------------ |
| `question`              | The question (positional, required)  |
| `--project`, `-p <dir>` | Project to analyze                   |
| `--attach`, `-a <file>` | Attach files; repeatable             |
| `--format`, `-f <type>` | `text` (default), `json`, `markdown` |

```bash theme={null}
buildwithtrace ask "What is R14 for?" --project ./my-board/
buildwithtrace ask "What trace width gives 90Ω differential on the inner layers?"
```

### buildwithtrace agent

Execute a single instruction. File writes are auto-approved.

```bash theme={null}
buildwithtrace agent "<instruction>" [options]
```

| Argument / Option       | Description                           |
| ----------------------- | ------------------------------------- |
| `instruction`           | What to do (positional, required)     |
| `--project`, `-p <dir>` | Project directory                     |
| `--attach`, `-a <file>` | Attach files; repeatable              |
| `--dry-run`             | Preview changes without applying them |

```bash theme={null}
buildwithtrace agent "Add test points to all power rails" --project ./my-board/
buildwithtrace agent "Rename net N$3 to USB_DP" --dry-run -p ./my-board/
```

### buildwithtrace plan

Multi-step plan mode: research → questions → plan → execute.

```bash theme={null}
buildwithtrace plan "<request>" [options]
```

| Argument / Option       | Description                               |
| ----------------------- | ----------------------------------------- |
| `request`               | The design request (positional, required) |
| `--project`, `-p <dir>` | Project directory                         |
| `--attach`, `-a <file>` | Attach files; repeatable                  |

```bash theme={null}
buildwithtrace plan "Design a 4-layer ESP32-S3 dev board with USB-C and a LiPo charger"
```

### buildwithtrace review

AI design review of a project.

```bash theme={null}
buildwithtrace review <project> [options]
```

| Argument / Option       | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| `project`               | Project path to review (positional, required)                     |
| `--scope <type>`        | `full` (default), `schematic`, `pcb`, `bom`                       |
| `--focus <areas>`       | Comma-separated: `routing,thermal,impedance,dfm,components,power` |
| `--format`, `-f <type>` | Output format                                                     |
| `--output`, `-o <file>` | Write the report to a file                                        |

```bash theme={null}
buildwithtrace review ./my-board/ --focus thermal,power --output review.md
buildwithtrace review ./my-board/ --scope schematic
```

### buildwithtrace signal

Trace electrical signal paths through schematic connectivity.

```bash theme={null}
buildwithtrace signal [net] [options]
```

| Argument / Option         | Description                                                     |
| ------------------------- | --------------------------------------------------------------- |
| `net`                     | Net name to trace (positional, optional if `--component` given) |
| `--component`, `-c <ref>` | Start from a component (e.g. `U7`)                              |
| `--pin <name>`            | Pin name/number to start from                                   |
| `--max-hops <n>`          | Max component hops (default `3`)                                |
| `--project`, `-p <dir>`   | Project directory                                               |
| `--format`, `-f <type>`   | Output format                                                   |

```bash theme={null}
buildwithtrace signal VCC --project ./my-board/
buildwithtrace signal --component U7 --pin 14 --max-hops 5
```

## Local validation & export

These run on a local **engine binary** — the same C++ command-line tool (`trace-cli`) that ships inside the Trace desktop app. On **macOS and Windows**, the Trace desktop app must be installed (the CLI detects it automatically). On **Linux**, if the desktop app isn't installed, the CLI downloads a standalone engine on first use. Manage it with [`buildwithtrace engine`](#buildwithtrace-engine). No account required.

<Accordion title="How engine detection works">
  The CLI searches for the engine binary in this order:

  1. **`TRACE_ENGINE_PATH`** environment variable (explicit override)
  2. **Trace desktop app** — `/Applications/Trace.app/Contents/MacOS/trace-cli` (macOS), `%LOCALAPPDATA%\Programs\Trace\*\bin\trace-cli.exe` (Windows), `/usr/bin/trace-cli` or `/opt/trace/bin/trace-cli` (Linux)
  3. **KiCad** — falls back to `kicad-cli` if Trace isn't installed (same engine, different branding)
  4. **Downloaded standalone** — `~/.trace/engine/trace-cli` (auto-downloaded on first use if none of the above exist)
  5. **`$PATH`** — checks `which trace-cli` or `which kicad-cli`

  If you have the Trace desktop app installed, you never need to download anything — `buildwithtrace erc`, `buildwithtrace drc`, and `buildwithtrace gerbers` just work immediately.
</Accordion>

### buildwithtrace erc

Run an Electrical Rule Check on a schematic.

```bash theme={null}
buildwithtrace erc <file> [--exit-zero]
```

| Argument / Option | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| `file`            | Schematic file (`.kicad_sch`)                                                     |
| `--exit-zero`     | Always exit `0`, even with violations (useful in CI gates you don't want to fail) |

Exits `10` if violations are found (unless `--exit-zero`), `5` if the engine isn't installed.

### buildwithtrace drc

Run a Design Rule Check on a PCB.

```bash theme={null}
buildwithtrace drc <file> [--exit-zero]
```

| Argument / Option | Description                           |
| ----------------- | ------------------------------------- |
| `file`            | PCB file (`.kicad_pcb`)               |
| `--exit-zero`     | Always exit `0`, even with violations |

### buildwithtrace gerbers

Export Gerber + drill files for manufacturing.

```bash theme={null}
buildwithtrace gerbers <file> [--output <dir>]
```

| Argument / Option      | Description                             |
| ---------------------- | --------------------------------------- |
| `file`                 | PCB file (`.kicad_pcb`)                 |
| `--output`, `-o <dir>` | Output directory (default `./gerbers/`) |

### buildwithtrace export

Export design files to other formats. The input file type is auto-detected from its extension.

```bash theme={null}
buildwithtrace export <subcommand> <input_file> [options]
```

| Subcommand | Input                        | Output         | Options                             |
| ---------- | ---------------------------- | -------------- | ----------------------------------- |
| `pdf`      | `.kicad_sch` or `.kicad_pcb` | PDF            | `-o/--output <dir>` (default `.`)   |
| `svg`      | `.kicad_sch` or `.kicad_pcb` | SVG            | `-o/--output <dir>`                 |
| `netlist`  | `.kicad_sch`                 | Netlist        | `-o/--output <file>`, `-f/--format` |
| `bom`      | `.kicad_sch`                 | BOM CSV        | `-o/--output <file>`                |
| `step`     | `.kicad_pcb`                 | 3D STEP        | `-o/--output <file>`                |
| `pos`      | `.kicad_pcb`                 | Pick-and-place | `-o/--output <dir>`                 |

`netlist --format` accepts `kicad` (default), `cadstar`, `orcadpcb2`, `spice`.

```bash theme={null}
buildwithtrace export pdf ./my-board/board.kicad_sch -o ./docs/
buildwithtrace export step ./my-board/board.kicad_pcb -o ./mech/board.step
buildwithtrace export netlist ./my-board/board.kicad_sch --format spice -o sim.cir
```

### buildwithtrace engine

Manage the local engine binary used by ERC/DRC/export.

```bash theme={null}
buildwithtrace engine [status|install|update]
```

| Action    | Description                                                    |
| --------- | -------------------------------------------------------------- |
| `status`  | Show whether the engine is installed and its version (default) |
| `install` | Download and install the engine                                |
| `update`  | Re-download the latest engine                                  |

## Format conversion

Local converters. No account required. Altium parsing uses a verified parser with netlist-driven connectivity for high-fidelity output.

<Note>
  **File formats.** `--format trace` writes Trace's line-oriented **text DSL** — `.trace_sch` for schematics, `.trace_pcb` for PCBs (grammars: `trace_sch.ebnf` / `trace_pcb.ebnf`). This is the canonical on-disk format the AI reads and writes, and it round-trips losslessly with KiCad. (`trace_json` is just an in-memory intermediate the converter passes through — it's never written to disk by `convert`.) `--format kicad` (the default) writes KiCad's native S-expression `.kicad_sch` / `.kicad_pcb`.
</Note>

### buildwithtrace convert schematic

```bash theme={null}
buildwithtrace convert schematic <input_file> [options]
```

| Argument / Option       | Description                              |
| ----------------------- | ---------------------------------------- |
| `input_file`            | `.SchDoc`, `.kicad_sch`, or `.trace_sch` |
| `--output`, `-o <dir>`  | Output directory (default `.`)           |
| `--format`, `-f <type>` | `kicad` (default) or `trace`             |

### buildwithtrace convert pcb

```bash theme={null}
buildwithtrace convert pcb <input_file> [options]
```

| Argument / Option       | Description                              |
| ----------------------- | ---------------------------------------- |
| `input_file`            | `.PcbDoc`, `.kicad_pcb`, or `.trace_pcb` |
| `--output`, `-o <dir>`  | Output directory                         |
| `--format`, `-f <type>` | `kicad` (default) or `trace`             |

### buildwithtrace convert project

Convert an entire Altium project directory (all `.SchDoc` + `.PcbDoc`, and writes a `.kicad_pro`).

```bash theme={null}
buildwithtrace convert project <input_dir> [--output <dir>]
```

```bash theme={null}
buildwithtrace convert schematic ./Board.SchDoc -o ./out/
buildwithtrace convert pcb ./Board.PcbDoc --format trace
buildwithtrace convert project ./LegacyAltiumProject/ -o ./kicad/
```

<Note>
  All conversions work out of the box — the local converter is bundled with the CLI. No extra install is required for Trace ↔ KiCad (`.trace_sch`/`.trace_pcb` ↔ `.kicad_sch`/`.kicad_pcb`) or Altium → KiCad.
</Note>

## Offline EDA helpers

These never touch the network or the AI — pure local parsing. Great for scripts and quick lookups.

### buildwithtrace index

Offline component and net lookup across your design files.

```bash theme={null}
buildwithtrace index <subcommand> [options]
```

| Subcommand        | Description                                             | Args           |
| ----------------- | ------------------------------------------------------- | -------------- |
| `component <ref>` | Show a component's value, footprint, library, pin count | `--project/-p` |
| `net <name>`      | List all component pins on a net                        | `--project/-p` |
| `list`            | List every indexed component                            | `--project/-p` |

```bash theme={null}
buildwithtrace index component U7
buildwithtrace index net VCC --project ./my-board/
buildwithtrace index list
```

### buildwithtrace rules

Manage `.trace/rules.md` — persistent design preferences the AI reads at the start of every conversation. See [TraceRules](/concepts/tracerules).

```bash theme={null}
buildwithtrace rules <subcommand> [--project <dir>]
```

| Subcommand     | Description                         |
| -------------- | ----------------------------------- |
| `show`         | Print the current `.trace/rules.md` |
| `init`         | Create a starter rules file         |
| `edit`         | Open the rules file in `$EDITOR`    |
| `set "<line>"` | Append a single rule line           |

```bash theme={null}
buildwithtrace rules init
buildwithtrace rules set "Always use 0402 passives unless I say otherwise"
buildwithtrace rules show
```

### buildwithtrace history

Read-only browser for the desktop app's `.history/` autosave repository. The CLI never writes to it (to avoid conflicting with the desktop app).

```bash theme={null}
buildwithtrace history <subcommand> [--project <dir>]
```

| Subcommand      | Description                    | Args                        |
| --------------- | ------------------------------ | --------------------------- |
| `list`          | List recent autosave snapshots | `--limit/-n` (default `30`) |
| `show <commit>` | Show a snapshot's diff stat    | —                           |

```bash theme={null}
buildwithtrace history list -n 50
buildwithtrace history show a1b2c3d
```

## Components, BOM & manufacturing

Backend commands (require auth).

### buildwithtrace components

```bash theme={null}
buildwithtrace components <subcommand> [options]
```

**`search "<query>"`** — search distributors (Nexar/DigiKey/Mouser):

| Option              | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `--type`, `-t`      | Filter: `resistor`, `capacitor`, `ic`, `connector`, … |
| `--package`, `-p`   | Filter: `0402`, `SOIC-8`, `QFP-48`, …                 |
| `--in-stock`        | Only in-stock parts                                   |
| `--limit`, `-l <n>` | Max results (default `10`)                            |

**`check`** — validate a BOM against distributor stock:

| Option                   | Description                         |
| ------------------------ | ----------------------------------- |
| `--bom`, `-b <file>`     | BOM file or project path (required) |
| `--distributors`, `-d`   | `jlcpcb,lcsc,digikey,mouser`        |
| `--suggest-alternatives` | Suggest pin-compatible alternatives |
| `--format`, `-f`         | `text`, `json`, `csv`               |

```bash theme={null}
buildwithtrace components search "LDO 3.3V 500mA" --package SOT-223 --in-stock
buildwithtrace components check --bom ./my-board/ -d jlcpcb,digikey --suggest-alternatives
```

### buildwithtrace bom

```bash theme={null}
buildwithtrace bom <subcommand> <project> [options]
```

**`enrich`** — fill in missing MPNs from distributors:

| Option                 | Description            |
| ---------------------- | ---------------------- |
| `--distributors`, `-d` | `nexar,digikey,mouser` |
| `--format`, `-f`       | `text`, `json`, `csv`  |

**`generate`** — full BOM generation:

| Option                  | Description                           |
| ----------------------- | ------------------------------------- |
| `--pricing`             | Include real-time pricing             |
| `--optimize`            | Suggest cost-optimized alternatives   |
| `--validate`            | Check parts are available and not EOL |
| `--format`, `-f`        | `csv`, `json`, `html`                 |
| `--output`, `-o <file>` | Write the BOM to a file               |

```bash theme={null}
buildwithtrace bom enrich ./my-board/ -d nexar
buildwithtrace bom generate ./my-board/ --pricing --validate -o bom.csv
```

### buildwithtrace generate

Generate KiCad symbols and footprints with AI. The component is generated server-side and the file is written to your project (`<name>.kicad_sym` / `<name>.kicad_mod`). Interactive runs ask for a credit-usage confirmation first.

```bash theme={null}
buildwithtrace generate symbol "<component>" [options]
buildwithtrace generate footprint "<component>" [options]
```

| Option                    | Description                                                                 |
| ------------------------- | --------------------------------------------------------------------------- |
| `--datasheet`, `-d <url>` | Datasheet URL for accurate pinout. If omitted, the part number is searched. |
| `--output`, `-o <dir>`    | Output directory for the generated file                                     |
| `--project`, `-p <dir>`   | Project directory                                                           |
| `--save`                  | Also save to your Trace library                                             |
| `--public`                | Make public in the community (requires `--save`)                            |

<Note>`--datasheet-file` (local PDF) is deprecated and not used by generation — pass a `--datasheet <url>`, or omit it and the part number will be searched for a datasheet automatically.</Note>

```bash theme={null}
buildwithtrace generate symbol "STM32F401" --datasheet https://st.com/.../stm32f401.pdf
buildwithtrace generate symbol "TPS563200" -o ./symbols/
buildwithtrace generate footprint "QFN-32 5x5mm 0.5mm pitch"
```

<Note>Datasheet questions ("what's the pinout of the STM32F401?") go through `buildwithtrace ask` or `agent` — the AI fetches and parses the datasheet itself (URL, part number, or an attached PDF) and answers with just the relevant section.</Note>

### buildwithtrace dfm

Design-for-manufacturing analysis.

```bash theme={null}
buildwithtrace dfm <subcommand> <project> [options]
```

| Subcommand | Description                                                   |
| ---------- | ------------------------------------------------------------- |
| `autofill` | Recommend optimal manufacturer parameters from board analysis |
| `check`    | Check the design against a manufacturer's capabilities        |

| Option                 | Description                                            |
| ---------------------- | ------------------------------------------------------ |
| `--manufacturer`, `-m` | `pcbway` (default), `pikkolo`, `jlcpcb` (`check` only) |
| `--format`, `-f`       | `text`, `json`                                         |

```bash theme={null}
buildwithtrace dfm autofill ./my-board/ -m pcbway
buildwithtrace dfm check ./my-board/ -m jlcpcb
```

### buildwithtrace order

Manufacturing order pipeline.

```bash theme={null}
buildwithtrace order <subcommand> [args]
```

| Subcommand            | Args                                     | Description                                   |
| --------------------- | ---------------------------------------- | --------------------------------------------- |
| `submit <project>`    | `-m/--manufacturer`, `--params`, `--bom` | Prepare an order (`pcbway`/`pikkolo`)         |
| `list`                | —                                        | List your PCB orders                          |
| `status <order_id>`   | —                                        | Live manufacturing status                     |
| `checkout <order_id>` | —                                        | Create a payment session and open the browser |
| `freight <order_id>`  | `--country`                              | Estimate shipping cost                        |
| `cancel <order_id>`   | —                                        | Cancel an order                               |

```bash theme={null}
buildwithtrace order list
buildwithtrace order status ord_abc123
buildwithtrace order freight ord_abc123 --country US
```

## Versions, teams, account & sharing

Backend commands (require auth).

### buildwithtrace versions

Schematic version snapshots (full file content, stored server-side).

| Subcommand             | Args                        | Description                                         |
| ---------------------- | --------------------------- | --------------------------------------------------- |
| `list <project>`       | `-n/--limit` (default `20`) | List saved versions                                 |
| `save [name]`          | `-p/--project` (required)   | Save the current schematic as a version             |
| `restore <version_id>` | `-o/--output`               | Restore a version (overwrites original unless `-o`) |

```bash theme={null}
buildwithtrace versions save "before routing" --project ./my-board/board.kicad_sch
buildwithtrace versions list ./my-board/board.kicad_sch
buildwithtrace versions restore 1a2b3c4d -o ./recovered.kicad_sch
```

### buildwithtrace teams

| Subcommand                 | Args                           | Description     |
| -------------------------- | ------------------------------ | --------------- |
| `list`                     | —                              | List your teams |
| `create <name>`            | —                              | Create a team   |
| `invite <team_id> <email>` | `-r/--role` (`member`/`admin`) | Invite a member |

### buildwithtrace billing

| Subcommand | Description                           |
| ---------- | ------------------------------------- |
| `status`   | Plan, usage %, credits, trial state   |
| `upgrade`  | Open the billing page in your browser |
| `portal`   | Open the Stripe customer portal       |

### buildwithtrace share

Shareable conversation links.

| Subcommand                 | Args | Description                           |
| -------------------------- | ---- | ------------------------------------- |
| `create <conversation_id>` | —    | Create a public share link            |
| `list`                     | —    | List your share links and view counts |
| `revoke <token>`           | —    | Revoke a link                         |

### buildwithtrace auth

| Subcommand | Options                                                                                               | Description                                                                                                                                                                                                                                                                      |
| ---------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `login`    | `--email/-e`, `--password`, `--token/-t`, `--no-browser`                                              | Authenticate. Default opens the browser to the login page (provider chosen in-browser, captcha solved there) and waits on a loopback callback. `--no-browser` prints the URL; `--token`/`--email`+`--password` are headless fallbacks. (`--provider` is deprecated and ignored.) |
| `logout`   | —                                                                                                     | Clear stored credentials                                                                                                                                                                                                                                                         |
| `status`   | —                                                                                                     | Account, plan, quota table                                                                                                                                                                                                                                                       |
| `token`    | `--create`, `--name <n>`, `--scope <s>` (repeatable), `--expires-days <n>`, `--list`, `--revoke <id>` | With no flags: print the current session token to stdout (for piping). `--create` mints a long-lived Personal Access Token (`trace_pat_...`, shown once); `--list`/`--revoke` manage them. Scopes: `mcp:all` (default) or `partner:read`.                                        |

```bash theme={null}
buildwithtrace auth token --create --name ci-bot --expires-days 90
buildwithtrace auth token --list
buildwithtrace auth token --revoke 1a2b3c4d
```

Token management (create/list/revoke) requires an **interactive login session** — a PAT can't manage tokens (enforced server-side, so a leaked PAT can't mint more or revoke yours). PATs can also be created in the dashboard (**Settings → Developer**, with a scope + expiry picker).

`buildwithtrace whoami` (top-level) prints the current user.

## Integrations

### buildwithtrace altium

Live bridge to a running Altium Designer instance (file-based IPC). Run `buildwithtrace altium install-scripts` first, then start `StartTraceServer` from the TraceAI script inside Altium.

| Subcommand         | Options                     | Description                                     |
| ------------------ | --------------------------- | ----------------------------------------------- |
| `install-scripts`  | `--dest`, `--force`         | Install the TraceAI DelphiScript files          |
| `status`           | —                           | Check whether the bridge is connected           |
| `serve`            | `--api-version`, `--resume` | Interactive chat against the open Altium design |
| `review`           | `--focus`, `--api-version`  | One-shot review of the open project             |
| `ask "<question>"` | `--api-version`             | Ask about the open design                       |
| `dfm`              | `--api-version`             | DFM analysis of the open PCB                    |

### buildwithtrace mcp

Expose Trace as a Model Context Protocol server. See [MCP Server](/resources/cli-mcp).

| Subcommand | Options        | Description                                |
| ---------- | -------------- | ------------------------------------------ |
| `serve`    | `-p/--project` | Start the stdio MCP server (requires auth) |
| `tools`    | —              | List the available MCP tools               |

### buildwithtrace byok

Bring your own LLM key. See [Bring Your Own Key](/resources/cli-byok).

| Subcommand         | Args    | Description                                                    |
| ------------------ | ------- | -------------------------------------------------------------- |
| `set <provider>`   | `--key` | Store a provider key and switch to it                          |
| `use <provider>`   | —       | Switch active provider (`anthropic`/`openai`/`gemini`/`trace`) |
| `model <model_id>` | —       | Set the model ID for your BYOK provider                        |
| `status`           | —       | Show the active provider and key state                         |
| `clear <provider>` | —       | Remove a stored key                                            |

## Configuration & diagnostics

### buildwithtrace config

| Subcommand          | Args | Description                                      |
| ------------------- | ---- | ------------------------------------------------ |
| `set <key> <value>` | —    | Set a config value (e.g. `env`, `output.format`) |
| `get <key>`         | —    | Read a config value                              |
| `list`              | —    | Show all config plus effective env/backend URL   |

`backend` is an alias for `env`. See [Configuration](/resources/cli-config).

### buildwithtrace doctor

Diagnoses API connectivity, authentication, the engine binary, Python version, installed copies, and your model provider. Exits non-zero if any check fails. Run it first whenever something misbehaves.

The CLI can be installed through several channels (pip, Homebrew, npm, or the curl installer). `doctor` reports the running copy's version and install origin, lists every `buildwithtrace` executable found on your `PATH`, and warns when multiple distinct installs coexist — `PATH` order decides which one runs, so keep one channel and uninstall the rest. `buildwithtrace --version` also shows the install origin, e.g. `v0.1.4 (homebrew)`.

```bash theme={null}
buildwithtrace doctor
```

## Exit codes

Commands use consistent exit codes so you can gate CI on them:

| 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 (e.g. `agent`/`plan` on the free plan) |
| `5`  | Engine not installed (run `buildwithtrace engine install`)                                          |
| `10` | ERC/DRC violations found                                                                            |

<Tip>
  In CI, pass `--exit-zero` to `buildwithtrace erc`/`buildwithtrace drc` when you want to collect results without failing the job, and omit it when violations should block the pipeline.
</Tip>