---
name: jlcpcb-parts
description: Search the JLCPCB / LCSC parts catalogue from the command line via the `jlcpcb-parts` CLI. Use when you need to find a JLCPCB-stocked part by MPN, function, package, parametric attributes (capacitance, voltage, resistance, tolerance, current, frequency, dielectric, etc.), or category; look up an LCSC number (`Cxxxxx`) for a KiCad symbol's `LCSC` property; check whether a given MPN is JLC Basic / Preferred / Extended; compare candidate parts by stock and unit price; verify a datasheet URL or partdetail link before placing an order; or discover what attribute keys exist for a category before filtering. Also use when sourcing alternates for an out-of-stock part, narrowing BOM choices to in-stock JLC parts, or resolving "which 0.1uF 0603 X7R 25V cap should I use" style questions.
---

# JLCPCB Parts

Plain-text CLI (no JSON) over a local snapshot of the JLCPCB / LCSC catalogue.

## Bootstrap (first run)

Before any subcommand:

1. `command -v jlcpcb-parts` — if found, skip the rest.
2. Otherwise inspect the host's Python (`which python3`, `pipx --version`, `uv --version`, `$VIRTUAL_ENV`, PEP 668 `EXTERNALLY-MANAGED`) and pick a fitting install method. Source URL is always `git+https://github.com/mash/jlcpcb-skills.git`. Examples — pick one, don't run blindly:
   - `pipx install git+…` (preferred when available)
   - `uv tool install git+…`
   - `pip install git+…` inside an active venv
   - PEP 668-locked system Python: install `pipx` first instead of `--break-system-packages`
3. Confirm with the user before touching system Python or using `--break-system-packages`.
4. Re-check `command -v jlcpcb-parts`. If still missing, fall back to `python3 -m jlcpcb_parts <args>` and tell the user how to fix PATH (`pipx ensurepath`, etc.).

## Commands

LCSC numbers display as `C2040`; inputs accept `C2040` or `2040`.

- `update` — refresh the cached SQLite (~100 MB DL → ~600 MB local).
- `search [<query>] [filters...]` — substring on MPN/description and/or filters (AND). Default limit 20.
- `show <LCSC>` — fields, attributes, price tiers, datasheet URL, partdetail URL. `partdetail` always emitted; other lines may be empty (record incomplete, not a CLI error).
- `schema` — categories with part counts.
- `schema <category>` — attribute keys + ≤8 sample values each.

### `search` filters

- `--category <name>` exact (use `schema` to discover)
- `--package <name>` exact (`0603`, `SOT-23-5`)
- `--manufacturer <name>` substring, case-insensitive
- `--min-stock <N>`
- `--basic` | `--preferred` (mutex)
- `--attr "Key OP Value"` repeatable. Ops: `=` `>=` `<=` `>` `<` `~`. SI numbers parsed (`0.1uF`, `25V`, `1k`).
- `--limit N` — applied after ordering
- `--text-fallback` — when `--attr` yields 0, retry by substring-matching attr values against MPN/description

Output: `LCSC MPN Pkg Type Stock $1 $100 Description`. Ordering: basic → pref → ext, then stock desc, then $1 asc.

**Attribute keys are category-specific and not guessable.** Run `schema <category>` first and copy the key verbatim (capitalisation matters). The `~` operator substring-matches text values.

## Cache

`$XDG_CACHE_HOME/jlcpcb-parts/components.sqlite3` (else `~/.cache/...`). Auto-downloads on first non-`update` command. Every run prints DB age to **stderr** (`# JLCPCB DB: built ... (Nd ago)`); ≥7d adds `⚠ run 'update'`.

## Examples

```bash
jlcpcb-parts search "STWLC38JRM"                    # MPN lookup
jlcpcb-parts show C14663                            # detail
jlcpcb-parts schema "Resistors"                     # discover attribute keys

# 0.1uF 0603 X7R 25V+ Basic — keys copied from `schema "Capacitors"`;
# always re-verify keys for other categories.
jlcpcb-parts search --category "Capacitors" --package 0603 \
    --attr "Capacitance=0.1uF" \
    --attr "Allowable voltage>=25V" \
    --attr "Temperature coefficient=X7R" \
    --basic --limit 10
```

## Troubleshooting (zero results — top-down)

1. **Wrong attribute key.** Re-run `schema <category>` and copy verbatim. Capacitors expose `Temperature coefficient` (X7R/C0G/NP0); some other subcategories expose `Dielectric`. Don't trust example keys for a different category.
2. **Operator too strict.** Swap `=` for `~` on text-ish attrs.
3. **Tier filter too narrow.** Drop `--basic` / `--preferred`.
4. **Corrupt attr fields.** yaqwsx occasionally mis-routes MPN tokens into wrong keys. Add `--text-fallback`.
5. **Absent from upstream.** yaqwsx drops parts OOS >120d, and a current part is occasionally missing from a snapshot. Try in **parallel** (concurrent searches, not serial):
   - shorter MPN substring (`CH32V003F4P6` → `CH32V003`) to catch reel/packaging suffixes
   - MPN with `-` `.` `()` stripped (vendor formatting differs from upstream rows)
   - `--manufacturer` substring
   - `--text-fallback` on the structured filter

   If still empty, **report the absence to the caller with the queries you tried**. Do not substitute an unrelated hit (e.g. an eval-kit SKU sharing a prefix), and do not scrape `jlcpcb.com` / `lcsc.com`. The caller supplies the C# manually; then `jlcpcb-parts show <C#>` distinguishes "missing locally" from "retired everywhere".
6. **Stale DB.** If stderr shows `⚠ DB is Nd old`, run `update`.

## Out of scope

- Writing LCSC# back to a KiCad symbol — use `kicad-tool`'s `sch edit set-property`.
- Live stock / price — the local DB is a ~6h snapshot.

## Scripts

`skills/jlcpcb-parts/scripts/jlcpcb_parts.py` is the entry point; `db_cache.py` and `search.py` are imports-only.