Trace CLI

PCB & schematic design from your terminal.

Website · Docs · Desktop App

---

Install

pip install buildwithtrace

Requires Python 3.10+. Installs the buildwithtrace command. (The CLI used to also install a trace binary, but that was dropped because it collides with macOS's system /usr/bin/trace. If you prefer the shorter name, add your own alias trace=buildwithtrace.)

Quick Start

# Authenticate
buildwithtrace auth login

# Ask a question about your design
buildwithtrace ask "What decoupling caps do I need for an STM32F4?"

# Full interactive chat with tool execution
buildwithtrace chat --project ./my-board/

# One-shot design review
buildwithtrace review ./my-board/

# Search for components
buildwithtrace components search "100nF 0402 MLCC"

Authentication

buildwithtrace auth login opens your browser to the Trace login page ({frontend}/login?callback=http://localhost:PORT) and waits on a loopback callback — you sign in there (password / Google / GitHub / magic link, captcha solved in-browser) and the tokens come back to the CLI. Tokens live in your OS keychain (fallback: a 0600 file).

For headless / CI machines, skip the browser:

buildwithtrace auth login --no-browser            # print the login URL to open elsewhere
buildwithtrace auth login --token trace_pat_xxx   # log in with a token
buildwithtrace auth login --email you@x.com --password '...'   # non-interactive

For CI, mint a long-lived Personal Access Token (trace_pat_..., shown once) and set it as an env var:

buildwithtrace auth token --create --name ci-bot   # --scope mcp:all|partner:read (repeatable), --expires-days 90
export TRACE_API_TOKEN=trace_pat_...               # used automatically on every command

buildwithtrace auth token --list                   # list your PATs
buildwithtrace auth token --revoke <id>            # delete one
buildwithtrace auth token                          # (no flags) print the current session token

Token management (create/list/revoke) requires an interactive login session — a PAT can't manage tokens (enforced server-side). PATs can also be created in the dashboard (Settings → Developer).

Commands

Command	Description
buildwithtrace auth	Login, logout, token management
buildwithtrace ask	Ask a question (read-only, no file changes)
buildwithtrace chat	Interactive AI chat with full tool execution
buildwithtrace plan	Multi-step planning mode (research, plan, execute)
buildwithtrace agent	Execute a single instruction (writes auto-approved)
buildwithtrace review	One-shot design review
buildwithtrace components	Search and check component availability
buildwithtrace bom	BOM generation and part enrichment
buildwithtrace generate	Generate symbols and footprints
buildwithtrace signal	Trace signal paths through schematic connectivity
buildwithtrace dfm	Design-for-manufacturing checks and autofill
buildwithtrace order	Track and manage PCB orders (submit in progress)
buildwithtrace versions	Save, list, and restore schematic versions
buildwithtrace teams	Create teams and invite members
buildwithtrace billing	View quota, plan status, upgrade
buildwithtrace share	Create and manage shareable conversation links
buildwithtrace erc / drc / gerbers	Local ERC/DRC/Gerber export (bundled engine)
buildwithtrace export	Export PDF, SVG, netlist, BOM, STEP, position files
buildwithtrace convert	Convert Altium ↔ KiCad ↔ Trace JSON
buildwithtrace index	Offline component/net lookup
buildwithtrace rules	Manage .trace/rules.md design preferences
buildwithtrace history	Browse local autosave history (read-only)
buildwithtrace byok	Bring your own LLM key (Anthropic/OpenAI/Gemini)
buildwithtrace mcp	Start MCP server for AI agent integration
buildwithtrace altium	Altium Designer bridge (file-based IPC)
buildwithtrace engine	Manage the local engine binary
buildwithtrace config	Manage CLI configuration
buildwithtrace doctor	Diagnose environment and connectivity issues

Run buildwithtrace --help or buildwithtrace <command> --help for detailed usage. Full reference: docs.buildwithtrace.com/resources/cli-commands.

MCP Integration

Trace exposes a Model Context Protocol server, enabling any MCP-compatible AI agent (Cursor, Codex, Claude Desktop, VS Code) to use Trace as a tool provider.

Remote Server (Recommended — zero install)

Add to your agent's MCP config (~/.cursor/mcp.json, claude_desktop_config.json, .codex/mcp.json):

{
  "mcpServers": {
    "trace": {
      "url": "https://mcp.buildwithtrace.com/mcp"
    }
  }
}

OAuth 2.1 handles auth automatically — browser popup on first use. For agents without OAuth, use a Bearer token via headers.

Cursor Marketplace (One-Click)

Search "Trace" in Cursor Settings > Plugins and click Install. Auto-updates included.

Local Server (for file-system access)

buildwithtrace mcp serve

Provides 4 local file tools (read_schematic, search_in_files, list_project_files, get_project_info) plus 8 remote tools and 4 prompt templates.

The Cursor marketplace / agent plugin lives in its own repo: @buildwithtrace/trace-plugin (npx plugins add buildwithtrace/trace-plugin).

Altium Designer Bridge

Connect Trace to a live Altium Designer session via file-based IPC. No SDK or DLL required.

# In your terminal
buildwithtrace altium serve

# In Altium: File > Run Script > TraceAI_Bridge.pas > StartTraceServer

Extracts schematic data, PCB placement, BOM, and netlist from your open Altium project. ~50ms round-trip per command.

See altium/README.md for setup instructions.

Configuration

# Switch between environments
buildwithtrace config set env production   # api.buildwithtrace.com (default)
buildwithtrace config set env staging      # staging server

# API version (default: latest — always the newest backend API).
# Pin one only if you need stability across backend releases.
buildwithtrace config set api_version latest   # default; or v4 / v3
buildwithtrace chat --api-version v4           # per-invocation override

# View current config
buildwithtrace config list

Credentials are stored in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service).

Updates

The CLI checks PyPI for a newer release at most once per 24h (cached, non-blocking) and prints a one-line notice to stderr when an upgrade is available:

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

The notice never touches stdout, so it won't corrupt piped or --json output. The check is automatically skipped in non-interactive contexts (pipes, CI, --json). To disable it entirely, set TRACE_NO_UPDATE_CHECK=1 (or TRACE_NO_ANALYTICS=1). Upgrade with pip install -U buildwithtrace (or brew upgrade buildwithtrace).

Bring your own key (BYOK)

Route the AI through your own provider key instead of Trace's hosted models. You pay your provider directly, so it skips Trace's cost cap — but you still need at least the plan that unlocks the mode (agent/plan require a trial/paid plan even with a key; ask is free).

buildwithtrace byok set anthropic --key sk-ant-...   # or omit --key to be prompted
buildwithtrace byok use openai                         # switch active provider
buildwithtrace byok use trace                          # back to Trace-hosted (default)
buildwithtrace byok model claude-sonnet-4-20250514     # set the model id
buildwithtrace byok status                             # show active provider + key state
buildwithtrace byok clear anthropic                    # remove a stored key

Providers: anthropic, openai, gemini. The key is stored in your keychain, never in config. The SDKs resolve BYOK from TRACE_LLM_PROVIDER / TRACE_LLM_API_KEY / TRACE_LLM_MODEL env (precedence: per-call args > env > persisted store). See the BYOK docs.

Analytics

The CLI (and SDKs) send anonymous, privacy-first usage analytics: command/method names, durations, exit codes, and version/OS info only — never file contents, paths, net/component names, or prompts. Auto-disabled in CI and for source installs. Opt out with TRACE_NO_ANALYTICS=1 or DO_NOT_TRACK=1.

Project Structure

This CLI is a thin wrapper over the core engine, which lives in the buildwithtrace-sdk package (the Trace class, HTTP/SSE client, auth + keyring, the local tool executor, the ERC/DRC/export engine manager, and BYOK resolution). The CLI depends on it (buildwithtrace-sdk>=0.1.0) and adds the terminal UX on top.

src/buildwithtrace/
├── main.py              # CLI entry point (Typer app)
├── commands/            # One file per command group
├── mcp/                 # MCP server (FastMCP)
├── altium/              # Altium bridge + altium_kicad converter
├── converter/           # trace_sch ↔ kicad_sch/pcb converter (bundled in the wheel)
├── ui/                  # Rich terminal renderer
├── auth_guard.py        # Plan/quota gating for paid commands
└── analytics.py         # Anonymous usage analytics (opt out: TRACE_NO_ANALYTICS=1 or DO_NOT_TRACK=1)

SDKs (build on Trace from code)

Prefer to drive Trace from your own scripts, services, or CI instead of the terminal? Two official SDKs wrap the same backend and are standalone agents — each runs the client-side tool-execution loop itself, so agent/plan work directly from code (file edits executed locally) without the CLI installed.

pip install buildwithtrace-sdk      # Python  → from buildwithtrace_sdk import Trace
npm install @buildwithtrace/sdk     # Node/TS → import { Trace } from '@buildwithtrace/sdk'

• Python SDK: buildwithtrace/sdk-python (PyPI buildwithtrace-sdk) — also the core this CLI depends on. The CLI re-exports Trace for backward compat (from buildwithtrace import Trace).
• Node SDK: buildwithtrace/sdk-node (npm @buildwithtrace/sdk).

Security

• File operations are sandboxed to the project directory
• Only allowed file extensions can be read or written
• Path traversal is prevented via resolved path validation
• Write operations require explicit user approval (bypass with --yes)
• Tokens are stored in your OS keychain, never in plaintext

Links

• Trace Desktop App
• Documentation
• Website

License

Proprietary. See LICENSE for details.

The .trace_* ↔ .kicad_* converter is the separate buildwithtrace-converter package (a dependency), which is proprietary ("All Rights Reserved") and governed by its own LICENSE. For licensing inquiries: hello@buildwithtrace.com