The Trace CLI is currently in development. The features described here are planned and not yet available. Available on Pro plans and above.
Why a CLI?
The Trace CLI lets you access Trace’s intelligence without the GUI. This means:
- Automation — Script repetitive design tasks, batch-process projects, export manufacturing files on a schedule
- CI/CD — Validate PCB designs in your build pipeline, run DRC/ERC checks on every commit, catch regressions before they hit production
- Headless AI — Run AI analysis, design reviews, and component checks from the terminal or a script
- Integration — Pipe Trace into your existing hardware team workflows, build custom tools on top of Trace’s capabilities
The CLI is the programmatic interface to everything Trace can do. If the GUI can do it, the CLI can too.
Installation
brew install buildwithtrace/tap/trace-cli
scoop bucket add trace https://github.com/buildwithtrace/scoop-bucket
scoop install trace-cli
npm install -g @buildwithtrace/cli
Authentication
This opens your browser to authenticate. Your API token is stored locally. For CI environments, set the TRACE_API_TOKEN environment variable:
export TRACE_API_TOKEN=your_api_token_here
Quick Start
# Create a new project
trace init my-board --layers 4
# Run a design review on an existing KiCad project
trace review ./my-project.kicad_pro
# Export Gerbers for JLCPCB
trace export --manufacturer jlcpcb ./my-project.kicad_pro
# Run DRC and fail if violations found
trace drc --strict ./my-project.kicad_pro
Core Commands
| Command | Description |
|---|
trace init | Create a new project |
trace export | Export manufacturing files (Gerber, BOM, STEP, pick-and-place) |
trace drc | Run Design Rule Checks |
trace erc | Run Electrical Rule Checks |
trace review | AI design review — analyze a project for issues |
trace ask | Ask the AI a question about a design |
trace components | Check component availability and pricing |
trace bom | Generate and validate a Bill of Materials |
trace auth | Manage authentication |
trace --help | Show help |
trace --version | Show version |
Use Cases
Batch Export
Export manufacturing files for multiple projects in one script:
for project in designs/*.kicad_pro; do
trace export --manufacturer jlcpcb --output "output/$(basename $project .kicad_pro)" "$project"
done
CI/CD Pipeline
Run DRC and ERC on every pull request. Example GitHub Actions workflow:
name: PCB Validation
on: [pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: buildwithtrace/setup-trace-cli@v1
- name: Run DRC
run: trace drc --strict --format json --output drc-report.json ./board.kicad_pro
env:
TRACE_API_TOKEN: ${{ secrets.TRACE_API_TOKEN }}
- name: Run ERC
run: trace erc --strict --format json --output erc-report.json ./board.kicad_pro
env:
TRACE_API_TOKEN: ${{ secrets.TRACE_API_TOKEN }}
- name: Upload reports
uses: actions/upload-artifact@v4
with:
name: validation-reports
path: "*.json"
Headless AI Design Review
Have Trace’s AI review a design and output a structured report:
trace review --format json ./board.kicad_pro > review.json
Component Availability Check
Check if all components in a BOM are in stock before ordering:
trace components check --bom ./output/bom.csv --distributors jlcpcb,digikey,mouser,ti
Scripted Design Tasks
Use trace ask to query designs from scripts:
# Get impedance analysis
trace ask "What trace width do I need for 50 ohm impedance on layer 2?" --project ./board.kicad_pro
# Explain a subcircuit
trace ask "Explain the power supply section of this design" --project ./board.kicad_pro --format markdown
--format for structured output:
| Format | Use case |
|---|
text | Human-readable terminal output (default) |
json | Machine-readable, for scripting and CI |
markdown | For reports and documentation |
csv | For BOMs and component lists |
Environment Variables
| Variable | Description |
|---|
TRACE_API_TOKEN | API authentication token (for CI/headless use) |
TRACE_PROJECT_DIR | Default project directory |
TRACE_OUTPUT_DIR | Default export output directory |
TRACE_LOG_LEVEL | Logging verbosity: debug, info, warn, error |
Stay Updated
Join our Discord or follow us on X for updates on CLI availability.
