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.

kicad-cli

NPX Install

Tags

SKILL.md Content

KiCad CLI Reference

1. Command Structure

2. Schematic Commands

Export Netlist

Export BOM

Export PDF

Export SVG

Run ERC (Electrical Rules Check)

3. PCB Commands

Run DRC (Design Rules Check)

Export Gerbers

Export Drill Files

Export Position/Pick-and-Place

Export 3D Models

Export PDF

Export SVG

Export DXF

4. Footprint Commands

Export SVG

Upgrade Footprint Library

5. Symbol Commands

Export SVG

Upgrade Symbol Library

6. Common Options

7. Automation Examples

CI/CD Build Script

JLCPCB Preparation

8. Exit Codes

9. Important Notes

What kicad-cli CAN Do

What kicad-cli CANNOT Do