CLI command design

bom

Exports bill-of-materials data from KiCad schematic or project inputs. The command uses the shared BOM/PnP normalization layer for canonical aliases, grouped JSON/CSV/XLSX, configurable DNP handling, optional PCB line items, variant selection, and JLC BOM rows.

Usage

kicad-cruncher bom project.kicad_pro --format json -o output/bom
kicad-cruncher bom schematic.kicad_sch --format xlsx
kicad-cruncher bom project.kicad_pro --variant B4
kicad-cruncher bom project.kicad_pro --format grouped-json
kicad-cruncher bom project.kicad_pro --format jlc-csv
kicad-cruncher bom project.kicad_pro --format jlc-xlsx
kicad-cruncher bom --write-config bom.config
kicad-cruncher bom project.kicad_pro --config bom.config

Arguments

file accepts .kicad_pro, .kicad_sch, or .kicad_pcb; schematic-sourced BOM output requires a schematic or project input. --format selects one legacy output format and overrides multi-output config mode. Without --format, the command loads bom.config from the working directory or creates it when absent. --config selects a specific docs/contracts/bom_pnp_config.v1.schema.json-shaped JSON or JSONC config path and also creates that path on first config-mode use. --write-config writes the documented default JSONC config without requiring a design file. --variant and --all-variants override config variant policy. -o is the legacy output directory or the config output root.

Config

The generated bom.config is JSONC with a single block-comment documentation header at the top and no inline comments in the object body. The schema contract is kicad_cruncher.bom.config.v1 in docs/contracts/bom_pnp_config.v1.schema.json. The same file drives bom, pnp, and jlc. field_aliases coalesces manufacturer, manufacturer part number, JLC/LCSC part number, value, description, and footprint fields with parameter values taking precedence over intrinsic fallbacks. bom.source_mode accepts schematic, pcb, and merged; KiCad merged currently resolves like schematic.

group_fields defines the manufacturable identity used to collapse components into one grouped line. The default ["mfg", "mpn", "description"] groups by canonical manufacturer, manufacturer part number, and description after alias coalescing. If all configured group fields are empty for a component, grouping falls back to value, footprint, and description so sparse parts still group deterministically. When split_dnp is true, fitted and DNP components are kept in separate groups even when their group fields match.

A component can become DNP from schematic symbol DNP state, footprint dnp attributes, or selected KiCad variant overrides. DNP components can remain in BOM review outputs when include_dnp is true, but they are never emitted in PnP/CPL outputs. BOM eligibility is separate: KiCad symbol not-in-BOM state, footprint exclude-from-BOM state, and virtual references such as power symbols remove a component from BOM output.

Output

Legacy output is written under the selected output directory using the input stem. Config output uses dir_template and name_template with project text variables plus Command, OutputKind, SourceName, SourceStem, and VariantName tokens. Configured BOM outputs include raw-json, legacy-json, grouped-json, grouped-csv, grouped-xlsx, jlc-csv, and jlc-xlsx. The generated default processes all variants including the no-variant base, writes raw-json and grouped-xlsx, groups by mfg, mpn, and description, and emits the grouped fields mfg, mpn, description, quantity, and designators. mfg and mpn are table-field aliases for the canonical manufacturer and manufacturer_part_number parameters; grouped table outputs also support generated fields such as item, quantity, designators, and dnp. raw-json is a flat list of unaliased component dictionaries from the selected KiCad source. Grouped XLSX output omits the line-number item column unless explicitly configured, writes spreadsheet-safe text cells, uses inverse knockout header styling, and does not enable Excel header filter dropdowns. Configured outputs write bom.config.used.json beside generated artifacts.

Tests

L0 verifies command registration and help. L3 workflow coverage exercises Yoshi BOM variants, DNP handling, grouped output, and JLC BOM rows. Unit tests cover alias resolution, config parsing, grouped BOM lines, natural designator sorting, raw JSON, DNP row placement, DNP XLSX highlighting, grouped table rows, XLSX generation, and JLC BOM rows.