| name | use-kicad-cli |
| description | Drives the KiCad command-line interface (`kicad-cli`, version 9.0) to export schematics and PCBs, produce fabrication outputs, and run design checks. This skill should be used when the user asks to export gerbers, drill, or pick-and-place files, generate a BOM or netlist, run ERC or DRC (including in CI), export a STEP/3D model or PDF/SVG, upgrade KiCad symbol/footprint libraries, or run a KiCad job set. Invoked via "/hardware:use-kicad-cli". |
| user-invocable | true |
| license | MIT |
| metadata | {"version":"1.0"} |
Use kicad-cli
Generate fabrication, documentation, and 3D outputs from KiCad projects, and run electrical/design rule checks, by driving kicad-cli — KiCad 9.0's command-line tool. It has six command groups: sch (schematic), pcb (board), sym (symbols), fp (footprints), jobset (batch job sets), and version.
Process
- Identify which artifact the user wants (fabrication files, BOM, a check, a 3D model, a PDF, a library upgrade) and map it to a command group with the table below.
- Locate and verify the binary before running anything (see "Locating the binary"). Run
kicad-cli version first to confirm it works.
- Load the matching reference file and use its exact flags. Do not invent flags — when unsure, run
kicad-cli <group> <command> -h.
- Build the command, create any output directory first, then run it. Report the produced files (and, for checks, the exit code plus report path).
CRITICAL operating rules
- macOS binary is not on PATH. On macOS it lives at
/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli. On Linux kicad-cli is on PATH; on Windows it is kicad-cli.exe in the KiCad bin folder. MUST confirm with kicad-cli version before building a pipeline.
- Checks silently pass without
--exit-code-violations. pcb drc and sch erc exit 0 by default even when violations exist — they only write a report. MUST pass --exit-code-violations to get exit 5 when violations are found. In CI, treat exit 5 as "violations found"; other non-zero codes are tool/IO errors. See references/checks.md.
--output is a directory for some commands, a file for others. Directory: pcb export gerbers, pcb export drill, */export svg (multi-file). File: pcb export pdf, pcb export step, pcb export pos, single-file exports. Create the directory first; never assume deep auto-creation.- Use
pcb export gerbers (plural). The singular pcb export gerber is deprecated in 9.0 and removed in 10.0.
- Stamp variables with
--define-var KEY=VALUE (-D) to override project text variables (e.g. ${REV}) at export time instead of editing the board. Protect KiCad field variables like ${QUANTITY} with single quotes in the shell so they are not expanded.
- Never hardcode the DRC/ERC JSON schema.
--format json is supported but its field names are not officially documented — generate a sample and inspect it before parsing.
- CI without a display:
kicad-cli generally runs headless, but some operations expect an X display. The robust pattern is the official kicad/kicad:9.0 Docker image, or Xvfb :99 -ac -nolisten tcp & then export DISPLAY=:99. See references/setup.md.
Command map
| User wants | Command | Reference |
|---|
| Gerbers / drill / pick-and-place | pcb export gerbers / drill / pos | references/pcb-export.md |
| Board PDF / SVG / DXF | pcb export pdf / svg / dxf | references/pcb-export.md |
| 3D model (STEP/GLB/VRML/…) | pcb export step / glb / vrml | references/pcb-export.md |
| IPC-2581 / IPC-D-356 / ODB++ | pcb export ipc2581 / ipcd356 / odb | references/pcb-export.md |
| Board render (PNG/JPEG) | pcb render | references/pcb-export.md |
| Schematic PDF / SVG / DXF / PS / HPGL | sch export <fmt> | references/sch-export.md |
| BOM / netlist | sch export bom / netlist | references/sch-export.md |
| Design / electrical rule check | pcb drc / sch erc | references/checks.md |
| Symbol/footprint SVG or library upgrade | sym ... / fp ... | references/sym-fp-jobset.md |
| Reproducible batch of outputs | jobset run | references/sym-fp-jobset.md |
| End-to-end recipes | — | references/workflows.md |
Locating the binary
Try, in order: kicad-cli on PATH; macOS /Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli; Windows C:\Program Files\KiCad\9.0\bin\kicad-cli.exe. Assign the resolved path to a shell variable and reuse it:
KCLI=$(command -v kicad-cli || echo /Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli)
"$KCLI" version
If none works, tell the user KiCad 9.0 is not installed or ask for the install path.
References
references/setup.md — locating the binary cross-platform, headless/CI setup, version, global options (--define-var, --output semantics), gotchas.references/pcb-export.md — every pcb export subcommand (gerbers, drill, pos, pdf, svg, dxf, step, glb, vrml, ipc2581, ipcd356, odb, others) plus pcb render.references/sch-export.md — sch export pdf/svg/dxf/ps/hpgl, netlist, bom, python-bom.references/checks.md — pcb drc and sch erc: flags, severity, exit codes, JSON caveat, CI gating.references/sym-fp-jobset.md — sym and fp export/upgrade, and jobset run.references/workflows.md — end-to-end recipes (fab package, CI checks, schematic PDF, STEP model, job set).
