Examples

Command Examples

Each block is one command, with a short explanation or sample output underneath. Terminal recordings demonstrate multi-step flows in context.

Sync & categories

Run sync before search --category so the CLI can resolve subcategory names. Browse names with categories.

bomi sync

Fetches the JLCPCB category tree into your shared cache (skips if data is fresh; use --force to refresh).

bomi sync --force

Re-downloads categories regardless of age.

bomi categories

Prints the full parent → child hierarchy with part counts.

bomi categories resistor

Narrows the printed tree to categories whose names match resistor. Subcategory lines are the strings to pass to search --category (after sync).

bomi search "10k 0402" --category "Chip Resistor - Surface Mount" --limit 5

Category-scoped search: the API filter uses the exact subcategory name; pick it from bomi categories output.

Recording: resistor categories, then search in “Chip Resistor - Surface Mount” (live API)

Search (live catalog)

search hits JLCPCB and writes hits into parts.db. Combine with stock, library, category, and price options.

bomi search "10k 0402 resistor"

Default live keyword search; results are cached locally.

bomi search "10k" --category "Chip Resistor - Surface Mount"

Server-side category filter after sync. Use an exact subcategory name (see bomi categories), not only a top-level parent.

bomi search "100nF" --category "MLCC"

Substring category matching when picking the --category argument; the CLI resolves to the API name.

bomi search "100nF capacitor" --basic-only

Basic library parts only (reduced assembly cost on JLCPCB).

bomi search "LED" --preferred-only --min-stock 1000

Preferred parts with at least 1k stock (API-side filters).

bomi search "STM32" --pages 3 --limit 50

Pagination: up to 3 × 50 rows before local trimming by --attr / --package / etc.

Recording: search USB-C and LED driver (live API)

Filters & attributes

--attr "Name operator value" works on search (after fetch) and query (SQL). Operators: >= <= > < = !=. SI prefixes: 10k, 100n, 4.7u. Multiple --attr are ANDed.

bomi search "0402 resistor" --attr "Resistance >= 10k"

Numeric parametric filter on normalized attributes.

bomi search "0402 capacitor" --attr "Voltage Rated >= 25"

Another numeric example (name must match the catalog attribute label).

bomi search "MOSFET SOT-23" --attr "Drain Source Voltage (Vdss) >= 30" --attr "Continuous Drain Current (Id) >= 5"

Two attributes; both must match.

bomi search "LDO 3.3V" --max-price 0.50 --basic-only

Price cap uses qty-1 pricing; combined with basic parts only.

bomi query --category "Slide Switches" --attr "Circuit = SP3T"

Local cache: category substring on stored parts.category, plus string equality on raw attribute text.

bomi query --category "Chip Resistor" --basic-only --attr "Resistance >= 10k"

Typical offline narrow-down after you have already populated the cache with search / fetch.

Output formats

Most research commands accept --format table|json|csv|markdown. Agents often want JSON.

bomi search "10k resistor" --format json

Envelope shape (truncated)

{
  "status": "ok",
  "command": "search",
  "count": 2,
  "results": [
    {
      "lcsc_code": "C8287",
      "mfr_part": "RC0402FR-0710KL",
      "manufacturer": "YAGEO",
      "package": "0402",
      "stock": 500000,
      "price_qty1": 0.0037
    }
  ]
}

bomi list --format json

BOM JSON uses "data", not "results" — important for parsers. Same for bom --format json.

Shape (truncated)

{
  "status": "ok",
  "command": "bom",
  "data": [
    {
      "ref": "R1",
      "lcsc": "C8287",
      "quantity": 2,
      "warnings": []
    }
  ]
}

bomi query "cap" --format csv

Exports matching cached rows as CSV (no API calls).

Local cache (`query`)

query never calls JLCPCB — only parts.db. Good for scripts and air-gapped filtering.

bomi query

Lists up to the default limit of cached parts (all rows if no keyword).

bomi query "resistor" --package 0402

Substring match on description / MFR / LCSC, plus package substring.

bomi query --category "Chip Resistor"

Restricts to cached rows whose category field contains the string.

bomi query --attr "Resistance >= 1k" --attr "Resistance <= 100k" --basic-only

Brackets a resistance window on cached attributes; basic parts only.

Fetch, info, compare

bomi fetch C8287

Resolves one LCSC code via search API and upserts the normalized part.

bomi fetch C8287 --force

Refreshes even when the row is younger than the default cache window.

bomi fetch C8287 C25900

Batch fetch by listing multiple codes.

bomi info C8287

Long-form view: attributes, pricing tiers, datasheet URL, JLCPCB link.

bomi info R1

When run inside a project, resolves designator R1 to an LCSC from project.yaml.

bomi compare C8287 C25900

Side-by-side table of fields and union of attribute names.

Recording: fetch and inspect a part

Recording: compare two switch options

Datasheets & analysis

Needs a working OpenRouter key for analyze and for datasheet --summary.

bomi fetch C347356

Ensure the part (and datasheet URL) is cached before analysis.

bomi analyze C347356

Default prompt returns markdown: key specs, pins, application hints, limits.

bomi analyze C347356 --prompt "What is the sense resistor formula for 350mA output?"

Targeted question when the default overview is not enough.

bomi analyze C347356 --model "anthropic/claude-sonnet-4.6"

Override the model for this run (see global default_model in config).

bomi datasheet C347356 --pdf -o docs/datasheets/

Downloads the PDF to the given folder (creates paths as needed).

bomi datasheet C347356 --pdf --summary -o docs/datasheets/

Writes .pdf and a .md summary next to it via OpenRouter.

UMW PT4115 C347356 LED Constant Current Driver Processed from PDF datasheet using anthropic/claude-sonnet-4.6

Project & BOM

Project commands need .bomi/project.yaml (or --project / BOMI_PROJECT).

mkdir my-board && cd my-board

Create a directory for the PCB repo (shell setup, not a bomi subcommand).

git init

Optional version control before bomi init.

bomi init --name "my-board" --description "Motor driver board"

Writes .bomi/project.yaml and can append datasheet lines to .gitignore.

bomi search "100nF 0402 X7R"

Research before selecting a line item.

bomi fetch C1525

Pin exact LCSC data in the cache.

bomi select C1525 --ref C1 --qty 1 --notes "Bypass cap"

Adds a BOM line; fetches automatically if the part is missing.

bomi list

Table of refs with package, price, stock; warnings for low stock or missing cache.

bomi list --check

Refreshes each selected LCSC from the live API, then re-displays.

bomi list --format markdown

Export a rich markdown BOM (grouped line items, detail tables).

bomi status

Text summary: cost roll-up at qty-1 pricing and consolidated warnings.

bomi relabel R1 R3

Renames a designator in project.yaml with overlap checks.

bomi deselect C2

Removes the selection with ref C2.

bomi --project ~/Projects/my-board list

Run BOM commands from another working directory.

export BOMI_PROJECT=~/Projects/my-board

Persists project path for the shell session (alternative to repeated --project).

git add "$BOMI_PROJECT/.bomi/project.yaml" && git commit -m "BOM: update selections"

Commit the project file when paths differ (adjust to your layout).

Recording: list + status — cost and stock

Recording: relabel, validate, export

Database

bomi db stats

Row counts for parts, attributes, analyses, categories.

bomi db clear

Destructive reset of the shared cache (prompts for confirmation). Paths: macOS ~/Library/Application Support/bomi/parts.db, Linux ~/.local/share/bomi/parts.db.