kicad-cruncher 2026.6.25

Cross-platform KiCad CLI workflows built on public kicad-monkey

KiCad Cruncher

kicad-cruncher is a cross-platform command-line application for KiCad design workflows. It consumes the public kicad-monkey package and keeps higher-level CLI behavior outside the core parser package.

The public commands generate KiCad-native design review bundles, project-local library bundles, cleaned library-ingestion bundles, project health reports, PCB SVG/STEP review artifacts, plugin tooling, and BOM/PnP/JLC manufacturing outputs from public kicad-monkey parsers/renderers.

Install

Install uv first if it is not already available:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

On macOS or Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install as a uv tool:

uv tool install kicad-cruncher
uv tool update-shell
kicad-cruncher --help

During local development:

uv sync --extra test
uv run kicad-cruncher --help
uv run python -m kicad_cruncher version

Commands

Run kicad-cruncher <command> --help for command-specific options.

Command	Purpose	Status
bom	Generate KiCad BOM outputs with shared field alias coalescing, variant-aware DNP handling, grouped JSON/CSV/XLSX review tables, and JLC BOM rows.	Public
daemon	Run the local plugin daemon and browser tool center used by KiCad IPC plugin workflows.	Public
design	Generate a design review bundle with KiCad-native design JSON, schematic SVGs, PCB copper-layer SVGs, a manifest, and a README for agents. Aliases: design-review, dr.	Public
health	Scan active project assets, model references, and project-listed local libraries without recursively importing unrelated library folders.	Public
jlc	Generate paired JLCPCB BOM XLSX and CPL XLSX upload workbooks from the shared BOM/PnP normalization layer.	Public
kicad	Inspect local KiCad installs, running KiCad-family processes, preferences, launch commands, and opt-in stop plans.	Public
lib-extract	Generate a cleaned lib_cruncher/Alexandria ingestion bundle with stripped symbols, footprints, optional models, and separated metadata JSON. Alias: library-extract.	Public
megamaid	Aggressively dissect a KiCad project into library artifacts, embedded assets, models, design review artifacts, netlists, SVGs, manifests, and README output.	Public
pcb	Run PCB utility commands, including config-driven PCB cleanup planning and explicit direct-file apply.	Public
pcb-layer-step	Generate compact colored STEP models for fixture-alignment checks on one KiCad PCB layer.	Public
pcb-svg	Generate PCB layer SVG artifacts and configured design views, including geometer-backed assembly HLR overlays.	Public
plugin	Install, inspect, and remove bundled KiCad IPC plugin packages.	Public
pnp	Generate KiCad pick-and-place JSON, CSV, XLSX, and JLC CPL outputs using component-center coordinates relative to the aux axis/drill-place file origin.	Public
project	Scaffold a new KiCad project (.kicad_pro + top-level .kicad_sch, optional embedded worksheet, library tables, PCB, title-block metadata, and text variables) from flags, a JSONC config, or the interactive --tui form.	Public
project-lib	Extract metadata-preserving project-local symbol and footprint libraries, defaulting to ./local-library/ and updating project library tables by default. Aliases: project-library, project-local-lib, local-library.	Public
schematic	Run schematic utility commands, currently exposing the deferred schematic cleanup planning stub.	Public
version	Print kicad-cruncher and controlled dependency versions.	Public

The design command writes to ./output/design/ by default. Its aliases design-review and dr produce the same output:

kicad-cruncher design board.kicad_pro
kicad-cruncher design-review board.kicad_pro
kicad-cruncher dr board.kicad_sch --no-indexes
kicad-cruncher design -o output/design

The design review output includes <input-stem>_design.json, design_review_manifest.json, README.md, enriched black-and-white schematic SVGs under schematics/, and one PCB review SVG per copper layer under pcb/copper_layers/ when a board is present. Schematic review SVGs preserve the kicad-monkey enrichment metadata while applying the kicad_cruncher.design_review.schematic_svg.a0 black-and-white role theme. PCB review SVGs include the copper layer, Edge.Cuts, and kicad-monkey enriched drill/slot records. Plated pads and vias, and KiCad np_thru_hole mechanical pads, are distinguished with data-hole-plating and data-hole-kind attributes. Design-review styling colors those existing records in place: plated drills are blue, plated slots are cyan, non-plated drills are red, and non-plated slots are orange. KiCad Cruncher does not add a second drill/slot overlay or duplicate the kicad-monkey plating metadata.

The pcb-svg command writes to ./output/pcb-svg/ by default and uses pcb.svg.config JSON/JSONC configs compatible with the A0 PCB SVG view contract. This remains a preview feature: SVG structure, virtual-layer metadata, default views, and config controls may change as more real-world boards are tested.

kicad-cruncher pcb-svg board.kicad_pcb
kicad-cruncher pcb-svg project.kicad_pro --views assembly-top
kicad-cruncher pcb-svg board.kicad_pcb --config pcb.svg.config -o output/pcb-svg

pcb-svg composes KiCad Monkey enriched physical layer SVG with explicit virtual layers. BOARD_OUTLINE and BOARD_CUTOUTS are synthesized from closed Edge.Cuts regions, with derived arc/curve/circle smoothness controlled by styles.board_outline.max_*_segment_mm, DRILLS and SLOTS preserve KiCad Monkey hole metadata, PIN1_TOP/PIN1_BOTTOM add configurable pad-linked marker groups, and ASSEMBLY_HLR_TOP/ASSEMBLY_HLR_BOTTOM append geometer-backed STEP hidden-line overlays or footprint-bound fallbacks. The assembly silhouette mode is named outline and uses Geometer's mesh-shadow outline algorithm by default. Use outline; legacy simple config values are no longer accepted. Default assembly views include only top and bottom assembly outputs. They include board cutouts, drills, slots, pin-1 markers, Geometer outline HLR with hole-first bounds fallback, and aspect-preserving fitted ASSEMBLY_DESIGNATORS_TOP/ ASSEMBLY_DESIGNATORS_BOTTOM labels drawn above the 75% opacity HLR/bounds overlay. Assembly labels are blue, bold monospace by default and rotate 90 degrees in the configurable ccw/cw direction when their fitted bounds exceed the configurable height/width aspect threshold. Assembly designator style overrides can target exact refs, prefixes, wildcards, or ranges.

The bom, pnp, and jlc commands provide initial KiCad manufacturing output support. They share a documented bom.config JSONC file with a top block summary, generated per-field comments, field aliases for manufacturer/part/JLC/value/description/footprint parameters, variant selection, DNP policy, grouping fields, PnP table fields, and output path templates.

kicad-cruncher bom project.kicad_pro
kicad-cruncher pnp project.kicad_pro --format xlsx
kicad-cruncher jlc project.kicad_pro --variant ADXL355
kicad-cruncher bom --write-config bom.config

PnP and JLC CPL output use the documented component-center mode, which maps to KiCad's footprint placement point relative to the aux axis, also called the drill/place file origin. Alternate geometric centroid modes are not exposed in this release.

The pcb-layer-step command writes fixture-alignment STEP artifacts under ./output/pcb-layer-step/ by default. The generated config is intentionally comment-heavy and can enable tracks, arcs, poured copper, vias, component pads, board outline/cutout bodies, drill overlays, and fused copper review bodies.

kicad-cruncher pcb-layer-step board.kicad_pcb
kicad-cruncher pcb-layer-step project.kicad_pro --doc board.kicad_pcb --layer bottom
kicad-cruncher pcb-layer-step --init-config --config pcb-layer-step.jsonc

Output Layout

Output-producing commands follow the same directory policy:

• when -o/--output is omitted, write artifacts under ./output/<command>/;
• when -o/--output is supplied, use that directory directly;
• command modules own filenames inside their command output directory.

Tests

Run the Rack suite:

uv run --extra test rack run --all

Run build and installed-console smoke tests:

uv run --extra test python -m build
uv run --extra test twine check dist/*
uv run --extra test python tests\support_scripts\install_test.py

Rack is the primary local gate. L0_public_cli covers startup and command manifest alignment, L3_public_workflows covers fixture-backed command behavior, and L99_signoff covers versioning, docs, contracts, source hygiene, ruff, and pyright.

Architecture Docs

• docs/adrs/ records accepted architecture decisions.
• docs/design/ records durable interface, command, data-flow, and format design notes.
• docs/contracts/ stores stable manifests and future schemas for public JSON or config formats.

Release Policy

Versioning, tagging, release, and traceability are defined in docs/adrs/ADR-0001-versioning-tagging-release-policy.md. The operator checklist lives in docs/release-process.md. Pushing a matching version tag triggers GitHub Actions publishing through PyPI Trusted Publishing/OIDC. Local Twine upload is fallback only.