Skip to main content
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)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us