kicad-library-install

Install or register a KiCad symbol/footprint library, and hand-generate .kicad_sch / .kicad_mod / .kicad_sym files, without silently corrupting the user's setup.

Five failure modes, each of which produces no error message or a misleading one:

1. Editing the lib tables while KiCad is running. They are read once at startup and written back from memory on exit, so your entry is invisible to the running instance and may be deleted when it closes. Symptom: Cannot add U1 (footprint 'Nick:Part' not found) while the file on disk plainly contains the entry.
2. A UTF-8 BOM in a lib table. KiCad reports has type UNINITIALIZED but expected SYMBOL; skipping and skips every library in the file. PowerShell's Set-Content -Encoding UTF8 writes one.
3. Namespacing lib_symbols sub-units. Only the top-level symbol carries the library nickname; prefixing _0_1 / _1_1 rejects the whole schematic with an unlocated Failed to load schematic.
4. A 3D model with a non-KiCad Z datum. KiCad expects origin at the seating plane; vendor STEP files are often top- or centre-referenced, so the part renders sunk into the board and the bad geometry bakes into downstream STEP/GLB exports.
5. Footprint internal name ≠ filename. KiCad renames on save and references drift.

Also documents the headless kicad-cli verification loop that catches all of them (the netlist export is the check that proves footprints resolve), running a control against a known-good project before blaming your own file, bisecting unlocated parse failures, and the defects to expect in vendor- or wiki-sourced parts.

What a correctly installed library looks like

Both halves render from the installed library, the netlist resolves every Footprint property to a real file, all 17 pins are present (including the exposed pad KiCad's vendor symbol omitted), and the 3D body sits on the board rather than inside it. Each of those is a separate check in this skill, and each fails silently when skipped.

Trap 4, drawn

Measure the STEP's Z extent before you swap a model. -h .. 0 means the origin is at the top of the body and the part will sink; 0 .. +h is what KiCad expects.

Companion to kicad-export-molecule (shipping a finished board), this one covers getting the libraries and generated files correct in the first place.