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

# Trace CLI

> Trace CLI brings AI-powered EDA to your terminal. Design, review, convert, and manufacture PCBs and schematics — powered by the same engine as the desktop app. Requires the desktop app on macOS/Windows; standalone on Linux.

<Info>
  The Trace CLI is in active alpha (`v0.1.0`). Everything on this page reflects the shipping command surface. The AI commands (`chat`, `agent`, `plan`, `review`, `ask`) run through the Trace backend — free accounts get `ask`; `agent`/`plan` require a paid plan, free agent credits, or an active legacy trial. The local commands (`erc`, `drc`, `gerbers`, `export`, `convert`, `rules`, `history`, `index`) work without a subscription.
</Info>

## What it is

`buildwithtrace` is a terminal interface for Trace's AI-powered EDA tools. On **macOS and Windows**, it requires the Trace desktop app to be installed (the CLI uses the desktop app's local engine). On **Linux**, the CLI downloads a standalone engine automatically on first use — no desktop app needed.

* **Design with AI** — `buildwithtrace chat`, `buildwithtrace agent`, and `buildwithtrace plan` give you the full agentic design loop, with file edits, tool execution, and plan mode, against your local `.kicad_sch` / `.kicad_pcb` / `.trace_sch` / `.trace_pcb` files.
* **Validate locally** — `buildwithtrace erc`, `buildwithtrace drc`, and `buildwithtrace gerbers` run on a bundled engine, no cloud round-trip required. Perfect for CI.
* **Convert anything** — `buildwithtrace convert` turns Altium (`.SchDoc` / `.PcbDoc` / `.PrjPcb`) into KiCad with netlist-accurate connectivity, and moves losslessly between KiCad and Trace's text DSL (`.trace_sch` / `.trace_pcb`).
* **Manufacture** — `buildwithtrace dfm`, `buildwithtrace bom`, `buildwithtrace components`, and `buildwithtrace order` take you from design to fab.
* **Integrate** — `buildwithtrace mcp serve` exposes Trace as a Model Context Protocol server so Cursor, Claude Desktop, or any MCP client can drive it. The GitHub Action drops it into CI.
* **Build on Trace** — the Python (`buildwithtrace-sdk`) and Node (`@buildwithtrace/sdk`) SDKs are **standalone agent clients**: they run the client-side tool-execution loop themselves, so `agent` and `plan` work directly from your own code without the CLI installed. See [SDKs](#sdks-build-on-trace-from-code).

The same Trace account, plan, quota, versions, and teams back both the desktop app and the CLI. Work you do in one shows up in the other.

## How it fits together

```
┌─────────────────────────────────────────────────────────┐
│  buildwithtrace (CLI)                                   │
│  • Local engine: ERC / DRC / Gerbers / PDF / SVG / STEP │
│  • Local converters: Altium ↔ KiCad ↔ Trace DSL         │
│  • Offline EDA index, rules, history (no network)       │
├─────────────────────────────────────────────────────────┤
│  api.buildwithtrace.com  (the same backend the app uses)│
│  • AI: chat / agent / plan / review / ask (SSE stream)  │
│  • Components, BOM, DFM, orders, versions, teams, billing│
└─────────────────────────────────────────────────────────┘
```

<Note>
  **The "local engine" IS the Trace desktop app's command-line binary** (`trace-cli`). On macOS and Windows, the desktop app must be installed — the CLI detects it automatically. On Linux, if you don't have the desktop app installed, the CLI downloads a standalone engine on first use. Either way, the commands work identically.
</Note>

AI requests stream over Server-Sent Events. Tool calls (read file, write, grep, run ERC/DRC, snapshot, etc.) are dispatched back to the CLI and executed **on your machine**, against your files — your designs never have to leave your disk for the AI to work on them.

<Tip>
  Bringing your own model key? `buildwithtrace byok set anthropic|openai|gemini` routes the AI through your provider (billed to you, not your Trace quota) while still using Trace's EDA tools and prompts. See [Bring Your Own Key](/resources/cli-byok).
</Tip>

## Install

The CLI is a Python package (`buildwithtrace`) and requires **Python 3.10+**. It installs a single command: `buildwithtrace`. (There's no `trace` binary — that name collides with the macOS system `/usr/bin/trace`.)

<Tip>
  Want a shorter command? Add your own shell alias — `alias trace=buildwithtrace`. Note this shadows the macOS system `/usr/bin/trace`, so skip it on macOS unless you're sure you don't need the system tool.
</Tip>

<Tabs>
  <Tab title="pip">
    ```bash theme={null}
    pip install buildwithtrace
    ```
  </Tab>

  <Tab title="pipx (isolated)">
    ```bash theme={null}
    pipx install buildwithtrace
    ```
  </Tab>

  <Tab title="Homebrew">
    ```bash theme={null}
    brew install buildwithtrace/tap/buildwithtrace
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g buildwithtrace
    ```

    The npm package downloads the Python wheel into an isolated virtualenv on `postinstall`. You still need Python 3.10+ on your machine.
  </Tab>

  <Tab title="GitHub Actions">
    ```yaml theme={null}
    - uses: buildwithtrace/github-action@v1
      with:
        token: ${{ secrets.TRACE_API_TOKEN }}
    ```

    See [Automation & CI/CD](/resources/cli-automation).
  </Tab>
</Tabs>

Verify the install:

```bash theme={null}
buildwithtrace --version
buildwithtrace doctor      # checks API connectivity, auth, engine, Python, model provider
```

## Authenticate

```bash theme={null}
buildwithtrace auth login
```

This opens your browser to the Trace login page (`{frontend}/login?callback=http://localhost:PORT/callback`) and waits on a loopback callback. You sign in **in the browser** — password, Google, GitHub, or magic link, with the captcha solved there — and the page bounces the tokens back to the CLI. (The old `--provider` flag is deprecated; the provider is now chosen in the browser.) Tokens are stored in your OS keychain (`com.buildwithtrace.cli`), falling back to a `0600` file if no keychain is available.

For headless / CI / SSH machines, skip the browser:

```bash theme={null}
# Recommended for CI — a long-lived Personal Access Token (see below)
export TRACE_API_TOKEN=trace_pat_xxx

# Or log in with a token explicitly
buildwithtrace auth login --token trace_pat_xxx

# Or print the login URL to open on another machine (no auto-open)
buildwithtrace auth login --no-browser

# Or non-interactive password login
buildwithtrace auth login --email you@example.com --password '...'
```

### Personal Access Tokens (CI/automation)

A browser login gives you a short-lived (\~1h) session JWT — fine for an immediate pipe, but it expires. For CI, mint a long-lived **Personal Access Token** (`trace_pat_...`, shown once):

```bash theme={null}
buildwithtrace auth token --create --name ci-bot
# optional: --scope mcp:all (default) / --scope partner:read, repeatable; --expires-days 90
export TRACE_API_TOKEN=trace_pat_...

buildwithtrace auth token --list           # your PATs (prefixes, scopes, expiry, last used)
buildwithtrace auth token --revoke <id>    # delete a PAT
buildwithtrace auth token                  # (no flags) print the CURRENT session token to stdout
```

Scopes are `mcp:all` (default — full CLI/MCP access) or `partner:read`. You can also create PATs in the dashboard (**Settings → Developer → Create Token**), which has a scope + expiry picker.

<Note>
  Creating, listing, and revoking tokens requires an **interactive login session** (a browser/email login) — a PAT cannot manage tokens. This keeps a leaked PAT from minting more tokens or revoking your others. (Enforced server-side.)
</Note>

Check who you are and your plan/quota at any time:

```bash theme={null}
buildwithtrace whoami
buildwithtrace auth status
```

## Quick start

```bash theme={null}
# Ask a question — read-only, no files touched (works on the free plan)
buildwithtrace ask "What decoupling caps does an STM32F4 need?"

# Full interactive design session against a project
buildwithtrace chat --project ./my-board/

# One-shot, single-instruction edit (writes auto-approved)
buildwithtrace agent "Add a 100nF decoupling cap to every IC power pin" --project ./my-board/

# Multi-step plan mode: research → questions → plan → execute
buildwithtrace plan "Design a USB-C PD trigger board for 20V output"

# AI design review, written to a file
buildwithtrace review ./my-board/ --focus thermal,power --output review.md

# Local validation (uses the bundled engine — no account needed)
buildwithtrace erc ./my-board/board.kicad_sch
buildwithtrace drc ./my-board/board.kicad_pcb
buildwithtrace gerbers ./my-board/board.kicad_pcb --output ./fab/

# Convert an Altium project to KiCad
buildwithtrace convert project ./LegacyBoard/ --output ./kicad-out/
```

## The command surface at a glance

| Command                      | What it does                               | Runs             |
| ---------------------------- | ------------------------------------------ | ---------------- |
| `buildwithtrace chat`        | Interactive AI design session              | Backend          |
| `buildwithtrace ask`         | One-shot read-only question                | Backend          |
| `buildwithtrace agent`       | Single auto-approved instruction           | Backend          |
| `buildwithtrace plan`        | Research → plan → execute                  | Backend          |
| `buildwithtrace review`      | AI design review                           | Backend          |
| `buildwithtrace signal`      | Trace a net/component through connectivity | Backend          |
| `buildwithtrace erc` / `drc` | Electrical / design rule checks            | Local engine     |
| `buildwithtrace gerbers`     | Gerber + drill export                      | Local engine     |
| `buildwithtrace export`      | PDF / SVG / netlist / BOM / STEP / pos     | Local engine     |
| `buildwithtrace convert`     | Altium ↔ KiCad ↔ `.trace_sch`/`.trace_pcb` | Local            |
| `buildwithtrace index`       | Offline component/net lookup               | Local            |
| `buildwithtrace rules`       | Manage `.trace/rules.md`                   | Local            |
| `buildwithtrace history`     | Browse `.history` autosave (read-only)     | Local            |
| `buildwithtrace components`  | Search / check parts                       | Backend          |
| `buildwithtrace bom`         | Generate / enrich BOMs                     | Backend          |
| `buildwithtrace generate`    | Generate symbols / footprints              | Backend          |
| `buildwithtrace dfm`         | DFM autofill / checks                      | Backend          |
| `buildwithtrace order`       | Manufacturing orders                       | Backend          |
| `buildwithtrace versions`    | Schematic version snapshots                | Backend          |
| `buildwithtrace teams`       | Team workspaces                            | Backend          |
| `buildwithtrace billing`     | Plan, quota, upgrade                       | Backend          |
| `buildwithtrace share`       | Shareable conversation links               | Backend          |
| `buildwithtrace altium`      | Live Altium Designer bridge                | Backend + bridge |
| `buildwithtrace byok`        | Bring your own LLM key                     | Local            |
| `buildwithtrace mcp`         | MCP server for AI assistants               | Local            |
| `buildwithtrace config`      | CLI configuration                          | Local            |
| `buildwithtrace engine`      | Manage the local engine binary             | Local            |
| `buildwithtrace doctor`      | Diagnose environment & connectivity        | Local            |
| `buildwithtrace whoami`      | Show current user                          | Local            |

See the full [CLI Command Reference](/resources/cli-commands) for every flag and argument.

## SDKs (build on Trace from code)

Prefer to drive Trace from your own scripts, services, or apps instead of the terminal? Two official SDKs wrap the same backend the CLI and desktop app use. They are **standalone agent clients** — each runs the client-side tool-execution loop itself, so the full agentic design loop (`agent` and `plan`, with file edits and tool calls executed locally against your files) works directly from the SDK, with **no CLI installed**.

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install buildwithtrace-sdk
    ```

    ```python theme={null}
    from buildwithtrace_sdk import Trace

    trace = Trace()  # reads TRACE_API_TOKEN / TRACE_API_KEY from the environment
    ```

    Requires **Python 3.10+**. Import root is `buildwithtrace_sdk` (distinct from the `buildwithtrace` CLI package).
  </Tab>

  <Tab title="Node">
    ```bash theme={null}
    npm install @buildwithtrace/sdk
    ```

    ```ts theme={null}
    import { Trace } from "@buildwithtrace/sdk";

    const trace = new Trace(); // reads TRACE_API_TOKEN / TRACE_API_KEY from the environment
    ```
  </Tab>
</Tabs>

The SDKs authenticate the same way as the CLI — a Trace account plus `TRACE_API_TOKEN` (or `TRACE_API_KEY`), see [Configuration](/resources/cli-config) — and hit the same backend, so your plan, quota, versions, and teams are shared across the desktop app, the CLI, and the SDKs.

<Note>
  The SDKs are a separate product from the `buildwithtrace` CLI. The CLI installs (`pip install buildwithtrace`, `brew install buildwithtrace/tap/buildwithtrace`, `npx buildwithtrace`) stay exactly as documented above — `buildwithtrace-sdk` / `@buildwithtrace/sdk` are *additional* packages for programmatic use, not replacements.
</Note>

## Security

The CLI executes AI tool calls (read, write, search-replace, delete) **locally on your machine**, behind the same sandbox the desktop app uses:

* **Project-directory sandbox** — every file path is resolved (`Path.resolve()`, symlink-safe) and must live inside the project directory. Paths that escape it are rejected.
* **Extension allowlist** — reads/writes are limited to EDA file types: `.trace_sch`, `.trace_pcb`, `.kicad_sch`, `.kicad_pcb`, `.kicad_sym`, `.kicad_mod`, Altium (`.SchDoc`, `.PcbDoc`, `.SchLib`, `.PcbLib`, `.PrjPcb`), plus `.svg`, `.zip`, `.gbr`, `.drl`, `.md`, and the `fp-lib-table` / `sym-lib-table` files. Anything else is blocked.
* **Write approval** — in `buildwithtrace chat`, write/search-replace/delete tools prompt for approval before touching disk. Pass `--yes` to auto-approve (e.g. for scripted runs). `buildwithtrace agent` auto-approves by design; `buildwithtrace ask` and `buildwithtrace review` never write.
* **Credentials** — auth tokens and BYOK keys live in your OS keychain (service `com.buildwithtrace.cli`), never in plaintext config. See [Configuration](/resources/cli-config#credential-storage).

Your design files never need to leave your machine for local commands (`erc`, `drc`, `gerbers`, `export`, `convert`, `index`). AI commands stream the relevant file content to the backend so the model can reason about it; tool execution always happens locally.

## Caveats & FAQ

### Local commands require the Trace desktop app (or KiCad)

<Warning>
  `buildwithtrace erc`, `drc`, `gerbers`, and `export` are thin wrappers around the **Trace desktop app's C++ engine binary** (`trace-cli`). You need the desktop app (or KiCad) installed on the same machine. The CLI cannot run these commands without it.
</Warning>

The CLI searches these locations for the engine:

| Priority | Location                                      | Notes                                            |
| -------- | --------------------------------------------- | ------------------------------------------------ |
| 1        | `TRACE_ENGINE_PATH` env var                   | Explicit override                                |
| 2        | `/Applications/Trace.app/` (macOS)            | Desktop app bundle                               |
| 3        | `%LOCALAPPDATA%\Programs\Trace\` (Windows)    | Desktop app install                              |
| 4        | `/usr/bin/trace-cli` or `/opt/trace/` (Linux) | System install or AppImage                       |
| 5        | `kicad-cli` in PATH                           | KiCad fallback (same engine, different branding) |

If none are found, the CLI shows: *"Trace/KiCad CLI not found. Install Trace from buildwithtrace.com"*

**Why not bundle it?** The engine is \~150 MB of compiled C++ with platform-specific GUI dependencies. Bundling it into a Python wheel would make installation impractical. The architecture is: lightweight Python CLI orchestrates → heavyweight C++ engine executes.

**Don't want the full desktop app?** On Linux, the CLI auto-downloads a self-contained engine on first use (\~200 MB AppImage). On macOS/Windows, the desktop app is required — it's a free download at [buildwithtrace.com/download](https://buildwithtrace.com/download).

<AccordionGroup>
  <Accordion title="Which commands need the engine and which don't?">
    **Need the engine (C++ binary):**

    * `buildwithtrace erc` — Electrical Rule Check
    * `buildwithtrace drc` — Design Rule Check
    * `buildwithtrace gerbers` — Gerber/drill export
    * `buildwithtrace export` — PDF/SVG/STEP export

    **Pure Python (no engine needed):**

    * `buildwithtrace convert` — format conversion (Altium ↔ KiCad ↔ Trace)
    * `buildwithtrace index` — local project indexing
    * `buildwithtrace rules` — TraceRules management
    * `buildwithtrace history` — git-based local history (needs `git` in PATH)
    * `buildwithtrace ask/chat/agent/plan/review` — AI commands (need network, not engine)
    * `buildwithtrace auth` — authentication
    * `buildwithtrace byok` — key management
    * `buildwithtrace doctor` — diagnostics
  </Accordion>

  <Accordion title="Engine version must match your files">
    If you save a file with Trace 1.4 and try to run ERC with an older engine (e.g., from a KiCad 8.0 install), you'll get "Failed to load schematic." The CLI detects this and suggests updating. Fix: update the desktop app from [buildwithtrace.com/download](https://buildwithtrace.com/download).
  </Accordion>

  <Accordion title="Python 3.10+ required (not 3.9 or earlier)">
    The CLI requires Python 3.10 at minimum. Common pitfalls:

    * **macOS:** The system Python (`/usr/bin/python3`) is often 3.9. Install via `brew install python@3.12` or `pyenv install 3.12`.
    * **Ubuntu 20.04 LTS:** Ships Python 3.8. Use the `deadsnakes` PPA: `sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.12`.
    * **Symptom:** `SyntaxError` or `ImportError` on install/import if version is too old.
  </Accordion>

  <Accordion title="AI commands require authentication + a paid plan or free agent credits">
    | Command  | Free plan (no credits left) | Free agent credits / Legacy trial / Paid |
    | -------- | --------------------------- | ---------------------------------------- |
    | `ask`    | ✓                           | ✓                                        |
    | `chat`   | ✗                           | ✓                                        |
    | `agent`  | ✗                           | ✓                                        |
    | `plan`   | ✗                           | ✓                                        |
    | `review` | ✗                           | ✓                                        |

    New accounts get [free agent credits](/guides/billing#free-agent-credits) (\~\$5 one-time + a small monthly top-up) that unlock the agentic commands until exhausted. The CLI shows a clear error ("Access denied — this feature requires a paid plan") if your plan doesn't support the command. Run `buildwithtrace auth status` to check.
    If your plan doesn't allow the mode, the CLI prints a clean upgrade CTA (no traceback) and exits with code `4`:

    > **Agent mode requires a paid plan.** Upgrade at buildwithtrace.com/pricing to continue — or use 'ask' mode (free), or bring your own key.

    Run `buildwithtrace auth status` to check your plan. **BYOK does not bypass this gate** — bringing your own key skips Trace's cost cap, but you still need at least the plan that unlocks `agent`/`plan` (free accounts can only use `ask`, even with their own key).

    Local commands (`erc`, `drc`, `gerbers`, `export`, `convert`, `index`, `rules`, `history`) never require auth or a subscription.
  </Accordion>

  <Accordion title="Altium conversion: known limitations">
    The Altium converter handles most real-world projects, but has known edge cases:

    * **Fonts:** Custom Altium fonts render as DM Sans. Text sizing may differ slightly.
    * **3D models:** Embedded STEP models are referenced but not extracted into separate files.
    * **Custom pad shapes:** Arbitrary polygon pads approximated as bounding primitive.
    * **Harness connectors & multi-level bus aliases:** Partially supported; deep nesting may lose connectivity.
    * **Expression-based design rules:** Converted to comments (KiCad DRC doesn't support expression rules).
    * **Large files (>200 MB PcbDoc):** No size guard — may use significant RAM on memory-constrained machines.
    * **Non-UTF-8 text:** Characters not representable in UTF-8 are replaced with `�`.

    If a conversion fails, the error message identifies the exact record or object that caused it. Report issues at `support@buildwithtrace.com`.
  </Accordion>

  <Accordion title="Conversion quality depends on available libraries">
    When converting `.trace_sch → .kicad_sch` or `.trace_pcb → .kicad_pcb`, the converter needs access to KiCad symbol/footprint libraries to produce accurate geometry. Without them:

    * **Symbols** get placeholder rectangles with correct pins but approximate dimensions
    * **Footprints** get placeholder pads based on pin count but imprecise geometry

    The CLI downloads KiCad symbol libraries (\~30 MB) to `~/.trace/libraries/` on first use. If the download fails (offline, GitHub unreachable), conversion still works but with reduced visual fidelity.
  </Accordion>

  <Accordion title="No 'trace' command (macOS system conflict)">
    The CLI installs only as `buildwithtrace`. macOS ships `/usr/bin/trace` (a kernel tracing tool) — shadowing it would break system debugging. For a shorter alias:

    ```bash theme={null}
    alias bt=buildwithtrace  # add to ~/.zshrc or ~/.bashrc
    ```
  </Accordion>

  <Accordion title="Credential storage and fallback behavior">
    The CLI stores auth tokens in your OS keychain:

    * **macOS:** Keychain Access (service `com.buildwithtrace.cli`)
    * **Windows:** Credential Manager
    * **Linux:** libsecret (GNOME Keyring / KWallet)

    **Fallback:** If the keychain is unavailable (locked, denied, headless server, Docker, missing `libsecret`), credentials fall back to `~/.config/trace/credentials.json`. The CLI does not warn you about this fallback.

    **CI/Docker:** Set `TRACE_API_TOKEN=trace_pat_xxx` as an environment variable instead. This bypasses the keychain entirely.
  </Accordion>

  <Accordion title="OAuth login in headless/SSH/WSL environments">
    `buildwithtrace auth login` opens a browser for OAuth. This fails in:

    * SSH sessions without X11 forwarding
    * WSL2 without `BROWSER` set
    * Docker containers
    * Headless CI servers

    **Workaround:** Log in on a machine with a browser, copy the token, and either:

    ```bash theme={null}
    buildwithtrace auth login --token trace_pat_xxx
    # or
    export TRACE_API_TOKEN=trace_pat_xxx
    ```
  </Accordion>

  <Accordion title="Corporate proxies and SSL inspection">
    The CLI respects standard proxy environment variables:

    ```bash theme={null}
    export HTTP_PROXY=http://proxy.corp.com:8080
    export HTTPS_PROXY=http://proxy.corp.com:8080
    ```

    **SSL inspection (MITM proxies):** If your corporate proxy injects custom CA certificates, you may get SSL errors. Fix:

    ```bash theme={null}
    export SSL_CERT_FILE=/path/to/corporate-ca-bundle.crt
    # or
    export REQUESTS_CA_BUNDLE=/path/to/corporate-ca-bundle.crt
    ```

    **Buffering proxies:** Some proxies buffer HTTP responses. This affects SSE streaming — you'll see long pauses then bursts of text instead of smooth streaming. The CLI still works correctly; it's a UX difference.

    Run `buildwithtrace doctor` to diagnose connectivity issues — it checks proxy settings and reports them.
  </Accordion>

  <Accordion title="CI/CD: ERC/DRC don't need auth or network">
    `buildwithtrace erc` and `buildwithtrace drc` run entirely locally (engine binary + files). They never contact the Trace backend. This means:

    * Work on forked PRs where secrets aren't available
    * Work fully offline
    * Work behind restrictive firewalls

    **Requirement:** The CI runner needs the Trace engine. On Linux runners (most common), the CLI auto-downloads the AppImage on first use. No manual setup needed:

    ```yaml theme={null}
    - name: Install Trace CLI
      run: pip install buildwithtrace
    - name: Run ERC
      run: buildwithtrace erc my-schematic.kicad_sch --exit-zero
    ```
  </Accordion>

  <Accordion title="Exit codes for CI integration">
    | Code | Meaning                                                                    |
    | ---- | -------------------------------------------------------------------------- |
    | `0`  | Success                                                                    |
    | `1`  | General failure (conversion error, API error, unexpected exception)        |
    | `2`  | Authentication required or failed                                          |
    | `5`  | Engine binary not found / unavailable                                      |
    | `10` | ERC/DRC found violations (design has issues but the command ran correctly) |

    Use `--exit-zero` on `erc`/`drc` to always return 0 (useful when you want violations as informational, not blocking).
  </Accordion>

  <Accordion title="Don't run two CLI instances on the same project">
    The CLI has no file locking. Running two `buildwithtrace agent` or `buildwithtrace chat` sessions against the same project simultaneously can result in:

    * Last-write-wins on `.trace_sch` / `.kicad_sch` files
    * Race conditions in the trace→kicad conversion

    The desktop app uses hash-based optimistic concurrency + per-file mutexes. The CLI does not (single-process design). If you need parallel AI sessions, use separate project directories or the desktop app.
  </Accordion>

  <Accordion title="AI file access is sandboxed">
    When the AI reads/writes files during `chat` or `agent` mode, it's restricted to:

    * **Only files inside your project directory** (path traversal blocked)
    * **Only EDA file types:** `.trace_sch`, `.trace_pcb`, `.kicad_sch`, `.kicad_pcb`, `.kicad_sym`, `.kicad_mod`, Altium formats, `.svg`, `.zip`, `.gbr`, `.drl`, `.md`, `.net`

    The AI **cannot** read your `.py`, `.json`, `.csv`, `.pdf`, `.png`, or other non-EDA files. If it tries, the CLI blocks it with a security error. This is intentional — the sandbox prevents accidental data exfiltration.
  </Accordion>

  <Accordion title="BYOK keys are stored in the OS keychain">
    `buildwithtrace byok set anthropic sk-ant-xxx` stores the key in your OS keychain, never in config files or shell history. To rotate: run `buildwithtrace byok set` again with the new key. To remove: `buildwithtrace byok clear`.
  </Accordion>

  <Accordion title="Offline mode is limited to local commands">
    Without network, AI commands fail immediately with a clear error. Local commands work fully offline as long as:

    * The engine binary is already installed (desktop app or KiCad present)
    * Symbol libraries are already cached (for conversion quality)

    Pre-cache everything while online: install the desktop app, then run `buildwithtrace convert` once to trigger library download.
  </Accordion>

  <Accordion title="'history' command requires git">
    `buildwithtrace history` uses your system `git` binary to read the `.history/` repository the desktop app maintains. If `git` is not in your PATH, the command fails with a clear error. Install git from [git-scm.com](https://git-scm.com/).
  </Accordion>

  <Accordion title="Analytics and error reporting opt-out">
    The CLI sends anonymous usage analytics (PostHog) and crash reports. Analytics is **privacy-first**: it records only command names, durations, exit codes, and version/OS info — **never** file contents, file paths, net/component names, or your prompts (a hard PII scrub drops anything that isn't a short enum/number/boolean). It's auto-disabled in CI, and source installs (no baked key) never phone home. To disable everywhere:

    ```bash theme={null}
    export TRACE_NO_ANALYTICS=1   # disable PostHog analytics
    export DO_NOT_TRACK=1         # cross-tool standard — also disables analytics
    export TRACE_NO_REPORTS=1     # disable crash report submission
    ```

    Add these to your shell profile for permanent opt-out.
  </Accordion>

  <Accordion title="Update-available notice">
    Once per 24h (cached, non-blocking), the CLI checks PyPI for a newer stable release and prints a one-line notice to **stderr** (never stdout, so piped/`--json` output is never corrupted):

    ```
    A new version of buildwithtrace is available: 0.1.0 -> 0.1.1
    Upgrade:  pip install -U buildwithtrace   (or: brew upgrade buildwithtrace)
    ```

    It's automatically skipped in CI, in JSON/non-TTY contexts, and for `buildwithtrace mcp`. Disable it entirely with `export TRACE_NO_UPDATE_CHECK=1` (or `TRACE_NO_ANALYTICS=1`).
  </Accordion>

  <Accordion title="Network timeouts during AI streaming">
    AI commands have a 300-second stream timeout. If the model takes longer (very complex tasks) or your connection is slow:

    * The CLI shows: "Stream timed out after 300s"
    * Partial output is still visible in your terminal
    * The conversation may be in an inconsistent state — start a new one rather than `--resume`

    If you're behind a buffering proxy, the effective timeout may feel shorter because idle time between chunks counts against it.
  </Accordion>
</AccordionGroup>

## Where to go next

<CardGroup cols={2}>
  <Card title="Command Reference" icon="rectangle-terminal" href="/resources/cli-commands">
    Every command, subcommand, flag, and exit code.
  </Card>

  <Card title="Bring Your Own Key" icon="key" href="/resources/cli-byok">
    Route the AI through your own Anthropic, OpenAI, or Gemini key.
  </Card>

  <Card title="MCP Server & Agent Plugin" icon="plug" href="/resources/cli-mcp">
    `npx plugins add buildwithtrace/trace-plugin` — skills + MCP for Cursor, Claude, Codex.
  </Card>

  <Card title="Automation & CI/CD" icon="robot" href="/resources/cli-automation">
    JSON output, exit codes, GitHub Actions, headless auth.
  </Card>

  <Card title="Configuration" icon="gear" href="/resources/cli-config">
    `config.toml`, environment variables, environments, credentials.
  </Card>

  <Card title="Roadmap" icon="map" href="/resources/cli-roadmap">
    What's shipped, what's coming, and the doc↔code gaps we're closing.
  </Card>

  <Card title="TraceRules" icon="scroll" href="/concepts/tracerules">
    Persistent design preferences the AI follows automatically.
  </Card>
</CardGroup>