Metadata-Version: 2.4
Name: buildwithtrace
Version: 0.1.4
Summary: CLI + SDK for Trace — AI-powered PCB & schematic design
Project-URL: Homepage, https://buildwithtrace.com
Project-URL: Documentation, https://docs.buildwithtrace.com/resources/cli
Project-URL: Repository, https://github.com/buildwithtrace/cli
Author-email: Trace <hello@buildwithtrace.com>
License: Trace CLI - Proprietary Software License
        
        Copyright (c) 2026 Trace (buildwithtrace.com). All rights reserved.
        
        This software and associated documentation files (the "Software") are
        proprietary to Trace. Unauthorized copying, distribution, modification,
        or use of this Software, via any medium, is strictly prohibited.
        
        You may not use, copy, modify, merge, publish, distribute, sublicense,
        or sell copies of the Software without prior written permission from Trace.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        CONVERTER DEPENDENCY:
        
        The .trace_* <-> .kicad_* converter is the separate buildwithtrace-converter
        package (a dependency of this CLI), which is proprietary ("All Rights Reserved")
        and governed by its own LICENSE. It is provided for reference only; you may not
        copy, modify, distribute, sublicense, sell, reverse-engineer, or create
        derivative works from it without explicit written permission.
        For licensing inquiries: hello@buildwithtrace.com
License-File: LICENSE
Keywords: ai,cli,eda,kicad,mcp,pcb,schematic
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Requires-Dist: buildwithtrace-converter>=0.1.4
Requires-Dist: buildwithtrace-sdk>=0.1.4
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: posthog>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer[all]>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://buildwithtrace.com">
    <img src="https://buildwithtrace.com/images/trace-icon.svg" alt="Trace" width="60" />
  </a>
</p>

<h1 align="center">Trace CLI</h1>

<p align="center">
  PCB &amp; schematic design from your terminal.
</p>

<p align="center">
  <a href="https://buildwithtrace.com">Website</a> ·
  <a href="https://docs.buildwithtrace.com/resources/cli">Docs</a> ·
  <a href="https://buildwithtrace.com/download">Desktop App</a>
</p>

---

## Install

```bash
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

```bash
# 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:

```bash
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:

```bash
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 route` | Autoroute a PCB (freerouting quick / cloud advanced) |
| `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 whoami` | Show the current authenticated user |
| `buildwithtrace doctor` | Diagnose environment, connectivity, and coexisting installs (pip/brew/npm/installer) |

Run `buildwithtrace --help` or `buildwithtrace <command> --help` for detailed usage. Full reference: [docs.buildwithtrace.com/resources/cli-commands](https://docs.buildwithtrace.com/resources/cli-commands).

## MCP Integration

Trace exposes a [Model Context Protocol](https://modelcontextprotocol.io) 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`):

```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)

```bash
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`](https://github.com/buildwithtrace/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.

```bash
# 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`](altium/README.md) for setup instructions.

## Configuration

```bash
# 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).

```bash
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](https://docs.buildwithtrace.com/resources/cli-byok).

## 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`](https://github.com/buildwithtrace/sdk-python) 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
├── 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.

```bash
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`](https://github.com/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`](https://github.com/buildwithtrace/sdk-node) (npm `@buildwithtrace/sdk`).

## Security

- File operations are sandboxed to the project directory
- Only [allowed file extensions](https://docs.buildwithtrace.com/resources/cli#security) 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](https://buildwithtrace.com/download)
- [Documentation](https://docs.buildwithtrace.com/resources/cli)
- [Website](https://buildwithtrace.com)

## License

Proprietary. See [LICENSE](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
