Public command

project-lib

Extract metadata-preserving KiCad project-local library artifacts for inspection and future relinking workflows.

Usage

kicad-cruncher project-lib project.kicad_pro
kicad-cruncher project-lib project.kicad_pro -o local-library
kicad-cruncher project-library project.kicad_pro --include-asset-scan
kicad-cruncher project-local-lib project.kicad_pro --validate-kicad-cli
kicad-cruncher project-lib project.kicad_pro --symbol-library-dir local-symbols --footprint-library-dir local-footprints
kicad-cruncher project-lib project.kicad_pro --include-models
kicad-cruncher project-lib project.kicad_pro --no-update-library-tables
kicad-cruncher project-lib project.kicad_pro --relink-dry-run
kicad-cruncher project-lib project.kicad_pro --relink-dry-run --repair-cache-links
kicad-cruncher project-lib project.kicad_pro --relink-sources
kicad-cruncher project-lib project.kicad_pro --relink-sources --validate-kicad-cli

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 ./local-library/. project-library, project-local-lib, and local-library are aliases for the same command. The default symbol folder is the .kicad_pro stem, and the default footprint folder is <.kicad_pro stem>.pretty. --symbol-library-dir and --footprint-library-dir override those folder names. --symbol-library-name and --footprint-library-name override the project table nicknames; when omitted, the nicknames come from the generated library folder names. --no-update-library-tables extracts artifacts without editing sym-lib-table or fp-lib-table, and may be combined with --relink-dry-run.

The command always uses project-local extraction mode: schematic symbols preserve metadata and project-specific variants, while PCB footprints are deduplicated by footprint library link down to the reusable common footprint set. Repeated embedded copies of the same schematic library symbol are collapsed by symbol member name so copied sheets do not create _2, _3, ... symbol files. KiCad-generated multipart alias members such as PART_1 are also collapsed when a base PART symbol exists.

--relink-dry-run writes source_relink.json with the schematic and PCB library-reference changes that would be made, without editing source files. --relink-sources applies those same targeted changes to placed schematic lib_id values, matching embedded schematic cache symbol names and their direct child unit symbol prefixes for placed symbols that use lib_id as their cache key without creating duplicate cache names, embedded schematic cache Footprint defaults for referenced symbols, placed schematic Footprint properties, and PCB footprint library links. Apply mode requires project library table updates so the generated local nicknames are registered before source files point at them. The flags are mutually exclusive and are never enabled by default.

Relink reports also validate KiCad schematic cache links: every placed symbol cache lookup key must exactly match an embedded lib_symbols cache symbol name in the same schematic. The lookup key is lib_name when present and lib_id otherwise. Reports also validate embedded cache unit names against KiCad's loader rule: a direct child unit symbol under a parent cache symbol must use the parent's library member name as its prefix and must keep the numeric _unit_bodyStyle suffix. Cache body validation verifies referenced embedded cache Footprint defaults are relinked the same way as generated local symbol libraries so KiCad does not warn that the schematic cache copy differs from the library copy. These checks catch KiCad-visible multipart alias failures, invalid unit-name prefixes, and symbol-cache/library mismatch warnings that tolerant parser lookups and KiCad CLI exports can otherwise hide. Dry-run reports list current issues and any unique repair candidate. Apply mode refuses to write source relinks while unresolved cache-link, cache-unit, or cache-body issues remain.

--repair-cache-links may be combined with --relink-dry-run or --relink-sources. It repairs only placed schematic lib_name values where the embedded cache has exactly one symbol with the same member name, such as changing PART_1 to local:PART_1. Ambiguous or missing candidates stay unresolved and block apply mode.

--no-embed-models disables board-embedded model payload rehydration in extracted footprints. --no-embed-external-models disables resolving external STEP/STP model paths into extracted footprints. --include-models additionally writes decoded embedded STEP/STP model files under models/, preserving model filenames instead of de-duplicating solely by payload hash. --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. In --relink-sources mode it also runs KiCad schematic ERC before and after source relinking, records project_erc_before.json and project_erc_after.json, and fails if post-relink library-hygiene findings remain or the ordinary ERC count changes. --kicad-cli selects the executable.

Ownership

The KiCad parsing, metadata preservation, model path classification, external STEP/STP embedding, metadata bundle construction, project library table editing, 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.

By default the command ensures project-local sym-lib-table and fp-lib-table entries exist for the generated symbol folder and footprint .pretty library. Existing nicknames are left unchanged. Generated symbol-library files have their internal symbol name normalized to the file member name, and their Footprint property is relinked to the generated footprint-library nickname when that footprint was extracted. Source schematic and PCB relinking is explicit through --relink-dry-run or --relink-sources; the command does not rewrite project text variables. Relinking updates embedded schematic cache symbol names, direct child unit symbol prefixes, and referenced embedded cache Footprint defaults only when required to keep placed cache lookups, KiCad unit parsing, and KiCad's cache-to-library symbol comparison exact. It skips parent cache renames when the target local cache name already exists. Schematic cache-link repair is also explicit through --repair-cache-links and only rewrites placed lib_name atoms with unique embedded-cache targets.

Output

The selected output directory contains a self-contained project-local library bundle:

<project-stem>/*.kicad_sym: metadata-preserving single-symbol KiCad symbol library files unless --symbol-library-dir selects another folder.
<project-stem>.pretty/*.kicad_mod: reusable standalone KiCad footprints, deduplicated by footprint library link across repeated placed instances unless --footprint-library-dir selects another folder.
models/*.{step,stp}: optional decoded embedded STEP/STP model payloads from the full project when --include-models or --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.
source_relink.json: optional kicad_cruncher.source_relink.a0 dry-run or apply report when --relink-dry-run or --relink-sources is used, including schematic cache-link validation, cache-unit validation, cache-body validation, and any planned cache-link repair changes.
project_erc_before.json and project_erc_after.json: optional raw KiCad schematic ERC JSON outputs written when --validate-kicad-cli is combined with --relink-sources.
project_lib_manifest.json: kicad_cruncher.project_lib_manifest.a0 artifact index with counts, relative output paths, mode, source project, project library table actions, optional KiCad CLI validation results, and optional project ERC hygiene summary.
README.md: short human-readable summary for agents and reviewers.

The library_extraction.json metadata follows docs/contracts/library_extraction_bundle.a0.schema.json. raw_fields is the raw KiCad parameter/property map with source key spelling preserved; canonical_fields is derived from those fields using case-insensitive alias matching for part fields such as mpn, mfg, value, description, and cad-reference.

megamaid handles cleaned lib_cruncher ingestion assets. project-lib handles metadata-preserving project-local assets. health handles broader asset diagnostics without extracting libraries.

Roadmap

Remaining project-local library hardening is tracked by docs/library/requirements/library-req-001-extraction-hardening.md. Source relinking and schematic cache-link repair are explicit, opt-in, report-backed, and covered by focused tests; follow-up work should continue hardening embedded asset extraction and real-world corpus validation.

Tests

L0 public CLI tests verify the command appears in root help, command help starts, relink flags are documented, dry-run writes source_relink.json, source apply changes only the targeted library-reference atoms, cache-link mismatches are reported, unique cache-link repairs are applied, duplicate embedded-cache targets are skipped, cache-unit prefixes are relinked, cache-body footprint defaults are relinked and idempotent, invalid cache-unit prefixes are reported, ambiguous or unresolved cache issues block apply mode without partial source writes, and the KiCad CLI before/after ERC hygiene gate is recorded in the manifest. L3 public workflow tests run project-lib against a temporary copy of the sanitized 4-ch backplane corpus fixture and verify manifest schema, project-stem output directories, CLI output-directory overrides, metadata schema, project-local preservation mode, footprint library-link dedupe, local table updates, idempotency, and aliases.