How to run ERC in KiCad from the command line reliably

What command-line ERC checks

KiCad’s electrical rules checker works from the logical information in a schematic: pin electrical types, net connections, no-connect flags, power symbols, and the rules stored with the project. It catches errors such as an output pin driving another output, a required input left open, or a power input that has no recognized power source. It does not know whether a chosen regulator is stable with your capacitors or whether two swapped GPIOs still satisfy the product requirements.

The command-line entry point is kicad-cli sch erc. Use the root .kicad_sch file as the input, even for a hierarchical design. KiCad follows the sheet hierarchy from that file.

First confirm which executable the shell will use:

kicad-cli version
kicad-cli sch erc --help

On macOS, a standard KiCad installation may put the binary inside the application bundle rather than on PATH:

/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli version

Pin the KiCad major version in CI. A report can change when a new major release adds a rule or changes a library, and silently running a developer’s KiCad 9 project through an older binary is a poor release test.

Run ERC and save a report

Run the command from the project directory. That gives KiCad the best chance of finding the matching .kicad_pro, project symbol libraries, ${KIPRJMOD} paths, and any text variables used by the schematic.

mkdir -p build/reports

kicad-cli sch erc \
  --output build/reports/erc.rpt \
  --severity-all \
  hardware/controller.kicad_sch

The default report format is plain text. --severity-all includes errors and warnings; excluded violations are not included unless you also request --severity-exclusions. A report is useful evidence, but this command alone does not necessarily fail a script merely because the report contains violations.

Add --exit-code-violations when ERC is a gate:

kicad-cli sch erc \
  --output build/reports/erc.rpt \
  --severity-all \
  --exit-code-violations \
  hardware/controller.kicad_sch

KiCad 9 returns status 0 when the selected severities contain no violations and status 5 when violations exist. Treat other nonzero codes as tool or input failures, not as ordinary ERC findings. In a CI step, the shell normally propagates that nonzero status and stops the job automatically.

For tooling that needs structured findings, select JSON explicitly:

kicad-cli sch erc \
  --format json \
  --output build/reports/erc.json \
  --severity-all \
  --exit-code-violations \
  hardware/controller.kicad_sch

Do not parse the human-readable .rpt format with a pile of regular expressions if JSON is available in the KiCad version you have pinned.

Choose a severity policy deliberately

--severity-error reports only error-level findings. --severity-warning reports warnings, and the flags can be combined. For a new project, gating on --severity-all is usually the cleanest policy because a growing warning list quickly becomes invisible background noise.

An existing board may need a staged cleanup. One practical sequence is:

1. Gate error-level findings immediately.
2. Save an all-severity report as a build artifact.
3. Fix or justify the existing warnings.
4. Change the gate to --severity-all once the baseline is clean.

If a finding is intentional, exclude that specific ERC marker in the Schematic Editor and record the reason. A blanket severity downgrade makes genuinely new problems easier to miss. During reviews, periodically run with --severity-exclusions so stale exceptions remain visible.

Fix the schematic, not the report

Open Inspect → Electrical Rules Checker in the Schematic Editor to inspect a failure in context. Double-clicking a marker takes you to the involved pins and nets. Common fixes include:

• placing a no-connect flag on a deliberately unused pin;
• correcting a symbol pin’s electrical type in a project library;
• adding PWR_FLAG where a net really is driven by an external or otherwise unrecognized source;
• joining wires that only appear to touch because their endpoints are off-grid;
• removing two different net labels from the same electrical net.

Do not scatter PWR_FLAG symbols over every power warning. The flag asserts that a net has a power source; it does not create one. Put it at the real source, such as a connector input, battery terminal, or regulator output whose symbol is modeled as passive.

ERC also cannot replace board checks. Once the schematic is clean, run PCB DRC and understand the KiCad DRC violations it reports. A schematic can be electrically consistent while its routed board contains a short, undersized track, malformed outline, or missing connection.

Put ERC in a repeatable check script

A minimal POSIX shell script can create artifacts and preserve KiCad’s status:

#!/usr/bin/env sh
set -eu

SCHEMATIC="hardware/controller.kicad_sch"
REPORT_DIR="build/reports"

mkdir -p "$REPORT_DIR"
kicad-cli sch erc \
  --format json \
  --output "$REPORT_DIR/erc.json" \
  --severity-all \
  --exit-code-violations \
  "$SCHEMATIC"

Commit the script, not generated reports. Run it on a clean checkout to expose missing project libraries or environment variables that happen to exist on one workstation. The broader headless KiCad automation workflow can run ERC, DRC, fabrication exports, and BOM generation under the same pinned toolchain.

Keep ERC early in that sequence. There is little value in plotting fresh Gerbers from a design whose source schematic has a known electrical conflict. After forward annotation, also run a schematic parity check so a clean schematic and a clean board are verified as the same design.

Know what a green ERC actually proves

A zero-violation report proves that the schematic satisfies the configured electrical rules at that revision. It does not validate datasheet limits, component ratings, connector pinouts, firmware assumptions, analog stability, signal integrity, or manufacturability. Those require design review and other checks.

That narrower promise is still valuable. Command-line ERC makes the exact same deterministic check easy to repeat before every merge and every manufacturing release, and it leaves a report showing what was checked rather than relying on somebody remembering to click a menu item.