ProvenMetal Sourcing for KiCad

[1]What it does

The plugin adds a Source with ProvenMetal button to KiCad. Click it and the plugin extracts your project's BOM, pushes it to ProvenMetal, and sources every line against distributor stock and lead times. In about a minute you get a verdict for each part, a summary window inside KiCad, and a link to the full web report.

Long-lead and unsourceable parts are the things that quietly kill a 7-day turn. This catches them while you're still in the schematic.

[2]Requirements

• KiCad 9.0 or newer— the plugin uses KiCad's IPC plugin API and reads the BOM via kicad-cli (bundled with KiCad).
• A ProvenMetal account — sign-in happens in your browser on first use, no API keys to paste.
• macOS, Windows, or Linux. No extra Python packages beyond what KiCad installs automatically.

The recommended way is through KiCad's Plugin and Content Manager using the ProvenMetal repository — you get one-click install and future updates show up automatically.

Option A — ProvenMetal repository (recommended)

1. 01In KiCad's project window, open Plugin and Content Manager and click Manage repositories (the gear icon).
2. 02Add this repository URL: https://provenmetal.com/kicad/repository.json
3. 03Select the ProvenMetal repository from the dropdown, find ProvenMetal Sourcing under Plugins, click Install, then Apply Pending Changes.

Option B — from the zip

1. 01Download the plugin zip (com.provenmetal.kicad_v0.2.0.zip). Don't unzip it.
2. 02In the Plugin and Content Manager, click Install from File... and select the zip.

Then, either way

1. 01Enable the KiCad API if you haven't already: Preferences → Plugins → Enable KiCad API, then restart KiCad.
2. 02Open your project's PCB in the PCB editor. The Source with ProvenMetal button appears in the toolbar.

Note:on KiCad 9 and 10 the plugin needs the board open in the PCB editor to find your project — clicking from the schematic editor alone won't work until KiCad 11.

[4]First run & sign-in

1. 01Save your project, open the PCB, and click Source with ProvenMetal. A progress window opens and streams what's happening.
2. 02Your browser opens for sign-in (Google by default). Approve it and you'll see “You're signed in. You can close this tab and return to KiCad.” Credentials are cached locally, so this only happens once.
3. 03The plugin exports your BOM, pushes it, and sourcing runs — usually well under a minute.
4. 04The window shows part counts (PARTS / PASS / REVIEW / FAIL) plus a “Needs attention” list, and the Open report button takes you to the full web report with every line and offer.

Set your build quantity before you trust the verdicts. “In stock” means in stock for your entire build, and the default is 1 board. Set it with board_count in settings (see section 7) or --board-counton the CLI — it's remembered per project after that.

[5]How it works

1. 01Extract.The plugin runs KiCad's own kicad-cli sch export bomagainst your root schematic, so hierarchical sheets, multi-unit symbols, and DNP handling behave exactly like KiCad's BOM export.
2. 02Read your fields. It looks for MPN, manufacturer, LCSC, Digi-Key, Mouser, and description fields under their common names (MPN, Manufacturer Part Number, LCSC, Digi-Key, ...). Custom field names can be mapped in settings.
3. 03Group. Rows are consolidated into orderable lines (by MPN, LCSC code, or value), references are merged, quantities summed, and DNP parts dropped.
4. 04Source.The BOM is pushed to ProvenMetal, which checks every line against live distributor stock and lead times. Passives without an MPN still source — we parametric-match from the value and description (“10uF 16V X5R 0603”), so a good Description field improves results.
5. 05Report. Each line comes back with a verdict, and the full report lives on the web with stock, lead times, and suppliers per line.

[6]Reading the verdicts

The threshold is deliberately strict: a part passes only if stock covers your whole build orit can be sourced within 7 days. That's what a fast turn actually requires. The in-KiCad window lists up to 15 flagged parts; the web report has everything.

[7]Settings

Options live in a settings.jsonfile in the plugin's config directory — on macOS ~/Library/Application Support/provenmetal-kicad/, on Windows %APPDATA%\provenmetal-kicad\, on Linux ~/.config/provenmetal-kicad/. All keys are optional.

[8]Project linking & the CLI

After the first run the plugin drops a small <project>.provenmetal.jsonsidecar next to your schematic. It links the KiCad project to its ProvenMetal project and remembers your board count, so re-runs update the same report instead of creating a new one. It's safe — and useful — to commit it to version control.

The plugin also runs headless for scripts and CI (KiCad 11+):

python -m provenmetal_kicad --login          # sign in once
python -m provenmetal_kicad --project ~/hw/my-board --board-count 25
python -m provenmetal_kicad --bom-csv bom.csv --no-open

[9]Troubleshooting

• Nothing happens when I click the button. Enable the API under Preferences → Plugins → Enable KiCad API and restart KiCad.
• “Couldn't find an open KiCad project.” Save the project to disk and open the board in the PCB editor, then click again.
• “Could not find kicad-cli.” Set kicad_cli_pathin settings to your KiCad install's kicad-cli binary.
• Warning about MPN / manufacturer fields. Your schematic uses field names the plugin doesn't recognize — map them with field_map in settings. Sourcing still runs on value + description in the meantime.
• Sign-in won't complete. The login uses a local browser redirect and times out after 5 minutes. Corporate firewalls that block localhost callbacks can interfere — try again on a normal network.
• Everything else. Each run writes a full trace to last-run.login the config directory (see section 7 for the path). Send it to us and we'll figure it out: founders@provenmetal.com.