jlcpcb-parts

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

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.