KiCad CLI Reference

Complete command reference for kicad-cli (KiCad 8.x)

1. Command Structure

bash

kicad-cli <application> <command> [options] <input-file>

Applications:

•sch - Schematic operations
•pcb - PCB operations
•fp - Footprint operations
•sym - Symbol operations

2. Schematic Commands

Export Netlist

bash

kicad-cli sch export netlist \
  --output project.net \
  project.kicad_sch

Export BOM

bash

# Basic BOM
kicad-cli sch export bom \
  --output bom.csv \
  project.kicad_sch

# With specific fields
kicad-cli sch export bom \
  --output bom.csv \
  --fields "Reference,Value,Footprint,LCSC,MPN" \
  --group-by "Value,Footprint" \
  --sort-asc \
  project.kicad_sch

Export PDF

bash

kicad-cli sch export pdf \
  --output schematic.pdf \
  --black-and-white \
  project.kicad_sch

Export SVG

bash

kicad-cli sch export svg \
  --output ./svg/ \
  --black-and-white \
  project.kicad_sch

Run ERC (Electrical Rules Check)

bash

kicad-cli sch erc \
  --output erc-report.rpt \
  --severity-all \
  --exit-code-violations \
  project.kicad_sch

Options:

•--severity-all - Report all severities
•--severity-error - Only errors
•--exit-code-violations - Return non-zero on violations

3. PCB Commands

Run DRC (Design Rules Check)

bash

kicad-cli pcb drc \
  --output drc-report.rpt \
  --severity-all \
  --exit-code-violations \
  project.kicad_pcb

Export Gerbers

bash

kicad-cli pcb export gerbers \
  --output ./gerbers/ \
  --layers "F.Cu,B.Cu,F.SilkS,B.SilkS,F.Mask,B.Mask,Edge.Cuts" \
  --subtract-soldermask \
  project.kicad_pcb

Common layers:

•F.Cu, B.Cu - Copper layers
•In1.Cu, In2.Cu - Inner copper layers
•F.SilkS, B.SilkS - Silkscreen
•F.Mask, B.Mask - Solder mask
•F.Paste, B.Paste - Solder paste
•Edge.Cuts - Board outline
•F.Fab, B.Fab - Fabrication layers

Export Drill Files

bash

kicad-cli pcb export drill \
  --output ./gerbers/ \
  --format excellon \
  --excellon-units mm \
  --generate-map \
  --map-format pdf \
  project.kicad_pcb

Options:

•--format excellon - Standard drill format
•--excellon-units mm or in
•--excellon-zeros-format decimal
•--generate-map - Create drill map
•--map-format gerberx2|ps|pdf|svg|dxf

Export Position/Pick-and-Place

bash

kicad-cli pcb export pos \
  --output positions.csv \
  --format csv \
  --units mm \
  --side front \
  --exclude-dnp \
  project.kicad_pcb

Options:

•--format csv|ascii
•--units mm|in
•--side front|back|both
•--exclude-dnp - Exclude Do Not Populate

Export 3D Models

bash

# STEP format (for mechanical CAD)
kicad-cli pcb export step \
  --output project.step \
  --subst-models \
  project.kicad_pcb

# VRML format
kicad-cli pcb export vrml \
  --output project.wrl \
  project.kicad_pcb

Export PDF

bash

kicad-cli pcb export pdf \
  --output pcb.pdf \
  --layers "F.Cu,B.Cu,Edge.Cuts" \
  --black-and-white \
  project.kicad_pcb

Export SVG

bash

kicad-cli pcb export svg \
  --output pcb.svg \
  --layers "F.Cu,Edge.Cuts" \
  --black-and-white \
  project.kicad_pcb

Export DXF

bash

kicad-cli pcb export dxf \
  --output pcb.dxf \
  --layers "Edge.Cuts" \
  project.kicad_pcb

4. Footprint Commands

Export SVG

bash

kicad-cli fp export svg \
  --output footprint.svg \
  footprint.kicad_mod

Upgrade Footprint Library

bash

kicad-cli fp upgrade \
  --output ./upgraded/ \
  ./library.pretty/

5. Symbol Commands

Export SVG

bash

kicad-cli sym export svg \
  --output ./symbols/ \
  library.kicad_sym

Upgrade Symbol Library

bash

kicad-cli sym upgrade \
  --output upgraded.kicad_sym \
  legacy.lib

6. Common Options

Option	Description
`--help`	Show command help
`--output`, `-o`	Output file/directory
`--define-var`	Define text variable
`--force`, `-f`	Overwrite existing files

7. Automation Examples

CI/CD Build Script

bash

#!/bin/bash
set -euo pipefail

PROJECT="myproject"

# Run ERC
echo "Running ERC..."
kicad-cli sch erc \
  --output reports/erc.rpt \
  --exit-code-violations \
  ${PROJECT}.kicad_sch

# Run DRC  
echo "Running DRC..."
kicad-cli pcb drc \
  --output reports/drc.rpt \
  --exit-code-violations \
  ${PROJECT}.kicad_pcb

# Generate manufacturing files
echo "Generating manufacturing files..."
mkdir -p output/gerbers

kicad-cli pcb export gerbers \
  --output output/gerbers/ \
  --layers "F.Cu,B.Cu,F.SilkS,B.SilkS,F.Mask,B.Mask,Edge.Cuts" \
  ${PROJECT}.kicad_pcb

kicad-cli pcb export drill \
  --output output/gerbers/ \
  --format excellon \
  ${PROJECT}.kicad_pcb

# Generate BOM
kicad-cli sch export bom \
  --output output/bom.csv \
  --fields "Reference,Value,Footprint,LCSC,MPN" \
  ${PROJECT}.kicad_sch

# Generate position file
kicad-cli pcb export pos \
  --output output/positions.csv \
  --format csv \
  --units mm \
  ${PROJECT}.kicad_pcb

echo "Done!"

JLCPCB Preparation

bash

#!/bin/bash
PROJECT="$1"
OUTPUT="./jlcpcb"
mkdir -p "$OUTPUT"

# Gerbers (zip for upload)
kicad-cli pcb export gerbers \
  --output "$OUTPUT/" \
  --layers "F.Cu,B.Cu,F.SilkS,B.SilkS,F.Mask,B.Mask,Edge.Cuts" \
  "${PROJECT}.kicad_pcb"

kicad-cli pcb export drill \
  --output "$OUTPUT/" \
  --format excellon \
  --excellon-units mm \
  "${PROJECT}.kicad_pcb"

cd "$OUTPUT" && zip -r gerbers.zip *.g* *.drl && cd -

# BOM for assembly
kicad-cli sch export bom \
  --output "$OUTPUT/bom.csv" \
  --fields "Comment,Designator,Footprint,LCSC" \
  "${PROJECT}.kicad_sch"

# CPL (Component Placement List)
kicad-cli pcb export pos \
  --output "$OUTPUT/cpl.csv" \
  --format csv \
  --units mm \
  --side front \
  "${PROJECT}.kicad_pcb"

8. Exit Codes

Code	Meaning
0	Success
1	General error
2	DRC/ERC violations found (with --exit-code-violations)

9. Important Notes

What kicad-cli CAN Do

•Export files (Gerber, PDF, SVG, netlist, BOM, 3D)
•Run validation (DRC, ERC)
•Upgrade library formats
•Automation and CI/CD

What kicad-cli CANNOT Do

•Modify designs (add components, routes)
•Edit schematic/PCB content
•Interactive operations

For design modifications, use:

•File manipulation (S-expression format)
•KiCad Python scripting console
•KiCad IPC API (experimental)

Version: This reference is for KiCad 8.x. Commands may differ in older versions.