lib-extract

Usage

kicad-cruncher lib-extract project.kicad_pro -o output/lib-extract
kicad-cruncher library-extract project.kicad_pro --dedupe fingerprint
kicad-cruncher lib-extract project.kicad_pro --include-asset-scan

Arguments

file accepts a .kicad_pro project. If omitted, the command auto-detects exactly one .kicad_pro in the current directory.

-o selects the output directory. Without -o, artifacts are written under ./output/lib-extract/. library-extract is an alias for the same command.

The command always uses internal extraction mode: symbols and footprints are stripped down to reusable KiCad library assets while raw metadata is preserved in JSON for downstream part association.

Power/global symbols are skipped because they are project wiring primitives, not part-library records. This includes cached library symbols marked with (power ...) and cached symbols whose raw Reference property is #PWR.

--dedupe name collapses repeated assets by library name. --dedupe fingerprint collapses by stripped serialized content. --no-embed-models disables board-embedded model payload rehydration. --no-embed-external-models disables resolving external STEP/STP model paths into extracted footprints. --all-embedded-models scans the whole project and writes every embedded STEP/STP payload. --include-asset-scan includes the full model-reference scan in the metadata JSON. --validate-kicad-cli asks KiCad CLI to parse/upgrade the generated libraries, and --kicad-cli selects the executable.

Ownership

The KiCad parsing, metadata stripping, model path classification, external STEP/STP embedding, metadata bundle construction, and KiCad CLI validation helpers are owned by kicad-monkey. kicad-cruncher owns command-line ergonomics, output directory layout, manifest writing, README writing, logging, and exit status.

The command is non-destructive. It does not edit the source project, update sym-lib-table or fp-lib-table, relink schematic symbols, relink PCB footprints, or rewrite project text variables. Project-local table editing belongs to project-lib.

Output

The selected output directory contains a library ingestion bundle:

• symbols/*.kicad_sym: one single-symbol KiCad symbol library file per extracted symbol record.
• footprints.pretty/*.kicad_mod: one standalone KiCad footprint per extracted footprint record.
• models/*.{step,stp}: decoded embedded STEP/STP model payloads required by the extracted footprint records, or every embedded payload when --all-embedded-models is used.
• library_extraction.json: kicad_cruncher.library_extraction_bundle.a0 metadata with raw fields, canonical identity fields, source paths, source references, model-reference diagnostics, and optional project asset scan when --include-asset-scan is used.
• lib_extract_manifest.json: kicad_cruncher.lib_extract_manifest.a0 artifact index with counts, relative output paths, mode, source project, and optional KiCad CLI validation results.
• README.md: short human-readable summary for agents and reviewers.

The metadata contract is docs/contracts/library_extraction_bundle.a0.schema.json. In each symbol or footprint record, raw_fields is the raw KiCad parameter/property map with source key spelling preserved and string values. canonical_fields is derived from raw_fields using case-insensitive alias matching and currently normalizes part fields such as mpn, mfg, value, description, and cad-reference. Import tools should treat unknown canonical keys as forward-compatible additions.

This command is intended for later lib_cruncher ingestion where the JSON metadata creates the part association and the symbol/footprint files are clean reusable CAD assets. Metadata-preserving project-local extraction is handled by project-lib; broader project dissection is handled by megamaid.

Tests

L0 public CLI tests verify the command appears in root help, command help starts, and the manifest/design-doc inventory stays synchronized. L3 public workflow tests verify the library-extract alias starts, run lib-extract --validate-kicad-cli against the sanitized 4-ch backplane corpus fixture with a fake kicad-cli, and assert that generated stripped symbol files are passed through sym upgrade while the generated footprint library is passed through fp upgrade. The underlying library extraction primitives remain covered by shared extraction tests.