use-kicad-cli

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

1. 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.
2. Locate and verify the binary before running anything (see "Locating the binary"). Run kicad-cli version first to confirm it works.
3. Load the matching reference file and use its exact flags. Do not invent flags — when unsure, run kicad-cli <group> <command> -h.
4. 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).