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.