CLI Reference

KiCad provides a comprehensive command-line interface (CLI) for automating design tasks, generating output files, and running checks without opening the GUI.

Basic Usage

kicad-cli [command] [subcommand] [options]

Getting Help

kicad-cli --help
kicad-cli --version
kicad-cli [command] --help

Common Options

Many commands share these options:

--help, -h - Show help message and exit
--version - Display version information
--output <path> - Specify output file or directory
--drawing-sheet <file> - Use custom drawing sheet (.wks file)
--define-var <VAR=VALUE>, -D - Define variable for text substitution
--variant <name> - Specify board variant to use

PCB Commands

pcb export

Export PCB designs to various formats.

Gerber Export

kicad-cli pcb export gerber [options] <input.kicad_pcb>

Options:

--output <dir>, -o - Output directory
--layers <layers> - Comma-separated layer list (e.g., F.Cu,B.Cu,Edge.Cuts)
--common-layers <layers> - Layers to include in all outputs
--drawing-sheet <file> - Custom drawing sheet
--exclude-refdes, --erd - Exclude reference designators
--exclude-value, --ev - Exclude component values
--include-border-title, --ibt - Include border and title block
--no-x2 - Disable Gerber X2 format (use X1)
--no-netlist - Disable netlist attributes
--subtract-soldermask - Subtract soldermask from silkscreen
--disable-aperture-macros - Use simple apertures only
--use-drill-file-origin - Use drill/place file origin
--precision <digits> - Coordinate precision (4-6, default: 6)
--no-protel-ext - Use KiCad file extensions instead of Protel

Example:

kicad-cli pcb export gerber \
  --output gerbers/ \
  --layers F.Cu,B.Cu,F.Mask,B.Mask,Edge.Cuts \
  --no-protel-ext \
  my_board.kicad_pcb

Drill File Export

kicad-cli pcb export drill [options] <input.kicad_pcb>

Options:

--output <dir>, -o - Output directory
--format <format> - Output format: excellon, gerber (default: excellon)
--drill-origin <origin> - Origin: absolute, plot (default: absolute)
--excellon-zeros <format> - Zero format: decimal, suppressleading, suppresstrailing, keep
--excellon-units <units> - Units: mm, in (default: mm)
--excellon-oval-format <format> - Oval holes: route, alternate
--generate-map - Generate drill map file
--map-format <format> - Map format: pdf, gerber, dxf, svg, ps
--gerber-precision <digits> - Coordinate precision (5-6, default: 5)

Example:

kicad-cli pcb export drill \
  --output drill/ \
  --format excellon \
  --drill-origin absolute \
  --excellon-units mm \
  --generate-map \
  --map-format pdf \
  my_board.kicad_pcb

PDF Export

kicad-cli pcb export pdf [options] <input.kicad_pcb>

Options:

--output <file>, -o - Output PDF file
--layers <layers> - Layers to include
--drawing-sheet <file> - Custom drawing sheet
--define-var <VAR=VALUE>, -D - Define variable
--mirror - Mirror output
--exclude-refdes - Exclude reference designators
--exclude-value - Exclude component values
--include-border-title - Include border and title block
--negative - Negative plot
--black-and-white - Force black and white
--theme <name> - Color theme to use
--drill-shape-opt <option> - Drill marks: 0 (none), 1 (small), 2 (actual)

Example:

kicad-cli pcb export pdf \
  --output assembly.pdf \
  --layers F.Cu,F.SilkS,F.Mask \
  --include-border-title \
  --theme "KiCad Default" \
  my_board.kicad_pcb

SVG Export

kicad-cli pcb export svg [options] <input.kicad_pcb>

Options: Similar to PDF export, plus:

--page-size <size> - Page size: A4, A3, A, B, C, D, E
--exclude-drawing-sheet - Exclude drawing sheet from output

DXF Export

kicad-cli pcb export dxf [options] <input.kicad_pcb>

Options:

--output <file>, -o - Output DXF file
--layers <layers> - Layers to export
--drawing-sheet <file> - Custom drawing sheet
--define-var <VAR=VALUE>, -D - Define variable
--output-units <units> - Output units: mm, in
--use-drill-file-origin - Use drill/place file origin

STEP/VRML 3D Export

kicad-cli pcb export step [options] <input.kicad_pcb>

Options:

--output <file>, -o - Output STEP file
--subst-models - Substitute 3D models with simplified shapes
--no-unspecified - Exclude components without 3D models
--no-dnp - Exclude DNP (Do Not Place) components
--board-only - Export board only (no components)
--include-tracks - Include tracks and vias
--include-zones - Include filled zones
--min-distance <dist> - Minimum distance for adjacent curves (default: 0.01mm)
--user-origin - Use user-defined origin
--origin <x,y,z> - Set custom origin coordinates

Example:

kicad-cli pcb export step \
  --output my_board.step \
  --no-dnp \
  --min-distance 0.01 \
  my_board.kicad_pcb

Position File Export

kicad-cli pcb export pos [options] <input.kicad_pcb>

Options:

--output <file>, -o - Output position file
--side <side> - Side to export: front, back, both
--format <format> - Format: ascii, csv, gerber
--units <units> - Units: mm, in
--bottom-negate-x - Negate X coordinate for bottom side
--use-drill-file-origin - Use drill/place file origin
--smd-only - Include SMD components only
--exclude-dnp - Exclude DNP components

IPC-2581 Export

kicad-cli pcb export ipc2581 [options] <input.kicad_pcb>

Options:

--output <file>, -o - Output IPC-2581 file
--units <units> - Units: mm, in
--compress - Compress output file

pcb drc

Run Design Rule Check.

kicad-cli pcb drc [options] <input.kicad_pcb>

Options:

--output <file>, -o - Output report file (JSON format)
--exit-code-violations - Return exit code 2 if violations found
--severity-all - Report all severities
--severity-error - Report errors only
--severity-warning - Report warnings and errors

Example:

kicad-cli pcb drc \
  --output drc_report.json \
  --exit-code-violations \
  --severity-error \
  my_board.kicad_pcb

if [ $? -eq 2 ]; then
  echo "DRC violations found!"
fi

pcb upgrade

Upgrade board file to current format.

kicad-cli pcb upgrade [options] <input>

Options:

--output <file>, -o - Output file (default: overwrites input)
--force - Force upgrade even if already current version

Schematic Commands

sch export

Export schematic to various formats.

PDF Export

kicad-cli sch export pdf [options] <input.kicad_sch>

Options:

--output <file>, -o - Output PDF file
--drawing-sheet <file> - Custom drawing sheet
--define-var <VAR=VALUE>, -D - Define variable
--black-and-white - Force black and white
--no-background-color - Remove background color
--exclude-drawing-sheet - Exclude drawing sheet
--theme <name> - Color theme

SVG Export

kicad-cli sch export svg [options] <input.kicad_sch>

Options similar to PDF export.

Netlist Export

kicad-cli sch export netlist [options] <input.kicad_sch>

Options:

--output <file>, -o - Output netlist file
--format <format> - Format: kicad, orcadpcb2, cadstar, spice, spicemodel

BOM Export

kicad-cli sch export bom [options] <input.kicad_sch>

Options:

--output <file>, -o - Output BOM file
--preset <name> - Use saved BOM preset
--format-preset <name> - Format preset (CSV, TSV, etc.)
--fields <fields> - Fields to include (comma-separated)
--labels <labels> - Field labels (comma-separated)
--group-by <fields> - Group by fields
--sort-field <field> - Sort by field
--sort-asc - Sort ascending
--filter <expr> - Filter expression
--exclude-dnp - Exclude DNP components

Example:

kicad-cli sch export bom \
  --output bom.csv \
  --fields "Reference,Value,Footprint,Datasheet,MPN" \
  --group-by "Value,Footprint" \
  --sort-field Reference \
  --exclude-dnp \
  my_schematic.kicad_sch

sch erc

Run Electrical Rule Check.

kicad-cli sch erc [options] <input.kicad_sch>

Options:

--output <file>, -o - Output report file (JSON format)
--exit-code-violations - Return exit code 2 if violations found
--severity-all - Report all severities
--severity-error - Report errors only
--severity-warning - Report warnings and errors

sch upgrade

Upgrade schematic file to current format.

kicad-cli sch upgrade [options] <input>

Symbol Commands

sym export svg

Export symbol to SVG.

kicad-cli sym export svg [options] <input.kicad_sym>

Options:

--output <dir>, -o - Output directory
--symbol <name> - Specific symbol to export (default: all)
--theme <name> - Color theme

sym upgrade

Upgrade symbol library to current format.

kicad-cli sym upgrade [options] <input>

Footprint Commands

fp export svg

Export footprint to SVG.

kicad-cli fp export svg [options] <input.pretty>

Options:

--output <dir>, -o - Output directory
--footprint <name> - Specific footprint to export (default: all)
--theme <name> - Color theme
--layers <layers> - Layers to include

fp upgrade

Upgrade footprint library to current format.

kicad-cli fp upgrade [options] <input>

Version Command

kicad-cli version

Displays KiCad version information including:

Version number
Build date
Commit hash
Libraries

Automation Examples

Complete PCB Manufacturing Package

#!/bin/bash

BOARD="my_board.kicad_pcb"
OUTPUT_DIR="manufacturing"

# Create output directory
mkdir -p "$OUTPUT_DIR"

# Run DRC
kicad-cli pcb drc \
  --output "$OUTPUT_DIR/drc_report.json" \
  --exit-code-violations \
  --severity-error \
  "$BOARD" || exit 1

# Generate Gerbers
kicad-cli pcb export gerber \
  --output "$OUTPUT_DIR/gerbers/" \
  --layers "F.Cu,B.Cu,F.Mask,B.Mask,F.SilkS,B.SilkS,F.Paste,B.Paste,Edge.Cuts" \
  --no-protel-ext \
  "$BOARD"

# Generate drill files
kicad-cli pcb export drill \
  --output "$OUTPUT_DIR/gerbers/" \
  --format excellon \
  --generate-map \
  --map-format pdf \
  "$BOARD"

# Generate position file
kicad-cli pcb export pos \
  --output "$OUTPUT_DIR/position.csv" \
  --format csv \
  --units mm \
  --side both \
  "$BOARD"

# Generate assembly PDF
kicad-cli pcb export pdf \
  --output "$OUTPUT_DIR/assembly_top.pdf" \
  --layers "F.Cu,F.SilkS,F.Mask,Dwgs.User" \
  --include-border-title \
  "$BOARD"

# Generate STEP model
kicad-cli pcb export step \
  --output "$OUTPUT_DIR/board.step" \
  --no-dnp \
  "$BOARD"

echo "Manufacturing files generated in $OUTPUT_DIR"

CI/CD Integration

# .gitlab-ci.yml example
validate:
  stage: test
  script:
    - kicad-cli pcb drc --exit-code-violations my_board.kicad_pcb
    - kicad-cli sch erc --exit-code-violations my_schematic.kicad_sch

generate_outputs:
  stage: build
  script:
    - kicad-cli pcb export gerber -o gerbers/ my_board.kicad_pcb
    - kicad-cli pcb export drill -o gerbers/ my_board.kicad_pcb
    - kicad-cli sch export bom -o bom.csv my_schematic.kicad_sch
  artifacts:
    paths:
      - gerbers/
      - bom.csv

Exit Codes

0 - Success
1 - Error (invalid arguments, file not found, etc.)
2 - Violations found (when using --exit-code-violations)

Contributing

Architecture

API Reference

CLI Reference

Basic Usage

Getting Help

Common Options

PCB Commands

pcb export

Gerber Export

Drill File Export

PDF Export

SVG Export

DXF Export

STEP/VRML 3D Export

Position File Export

IPC-2581 Export

pcb drc

pcb upgrade

Schematic Commands

sch export

PDF Export

SVG Export

Netlist Export

BOM Export

sch erc

sch upgrade

Symbol Commands

sym export svg

sym upgrade

Footprint Commands

fp export svg

fp upgrade

Version Command

Automation Examples

Complete PCB Manufacturing Package

CI/CD Integration

Exit Codes

See Also

​Basic Usage

​Getting Help

​Common Options

​PCB Commands

​pcb export

​Gerber Export

​Drill File Export

​PDF Export

​SVG Export

​DXF Export

​STEP/VRML 3D Export

​Position File Export

​IPC-2581 Export

​pcb drc

​pcb upgrade

​Schematic Commands

​sch export

​PDF Export

​SVG Export

​Netlist Export

​BOM Export

​sch erc

​sch upgrade

​Symbol Commands

​sym export svg

​sym upgrade

​Footprint Commands

​fp export svg

​fp upgrade

​Version Command

​Automation Examples

​Complete PCB Manufacturing Package

​CI/CD Integration

​Exit Codes

​See Also

Basic Usage

Getting Help

Common Options

PCB Commands

pcb export

Gerber Export

Drill File Export

PDF Export

SVG Export

DXF Export

STEP/VRML 3D Export

Position File Export

IPC-2581 Export

pcb drc

pcb upgrade

Schematic Commands

sch export

PDF Export

SVG Export

Netlist Export

BOM Export

sch erc

sch upgrade

Symbol Commands

sym export svg

sym upgrade

Footprint Commands

fp export svg

fp upgrade

Version Command

Automation Examples

Complete PCB Manufacturing Package

CI/CD Integration

Exit Codes

See Also