bomi — Agent Reference

This guide is designed to be read at the start of a Claude Code, Copilot, or Cursor session. It gives the agent everything it needs to use bomi correctly.

In practice, bomi is used inside a hardware project folder: .bomi/project.yaml stores the project BOM selections, bomi list/status generate BOM views from that file, and bomi datasheet can write PDFs plus markdown summaries into a docs folder such as docs/datasheets/. Part and category data are cached locally, so agents can fetch, search, query, info, and compare parts without repeated browser work. Datasheet analysis and markdown summaries require openrouter_api_key in the global config file (~/Library/Application Support/bomi/config.yaml on macOS, ~/.local/share/bomi/config.yaml on Linux).

Quick rules

• sync fetches the JLCPCB category tree into the local cache (skips if already fresh; --force to refresh). Run it before search --category.
• search is live and also updates the local cache. search --category resolves a synced subcategory name for the API. query --category uses substring matching on cached parts.category instead.
• query is local-cache only — fast and offline.
• --package, --min-stock, --max-price, and --attr use the same rules for search (after results are normalized) and query (SQL). --basic-only / --preferred-only apply on the API for search and in SQL for query, but are not re-checked locally after a search.
• info, compare, analyze, and datasheet need the part in the local cache — run fetch if needed. select fetches automatically when the part is missing.
• select, list/bom, status, deselect, and relabel need project context (a .bomi/project.yaml in the tree).
• fetch --all and datasheet --all process selected LCSC parts from the active project BOM.
• status is text-only. list --format json (and bom --format json) uses a different JSON shape than other commands — see Output Format.

Command reference

Command	Purpose
bomi sync	Fetch and cache the JLCPCB category tree
bomi categories	List cached categories (hierarchy)
bomi categories "filter"	List categories whose name contains filter
bomi search "keyword"	Search the live JLCPCB catalog
bomi search "keyword" --category "Subcat Name"	Live search scoped to a synced subcategory (after sync)
bomi fetch CXXXXX	Cache a specific part by LCSC code
bomi fetch --all	Cache all selected LCSC parts from the active project BOM
bomi query "keyword"	Search the local cache only
bomi query --category "name"	Filter the local cache by category substring (LIKE on parts.category)
bomi info R1	Show full details for the part selected at a designator
bomi info CXXXXX	Show full details for one cached part by LCSC code
bomi compare CXXXXX CYYYYY	Compare cached parts side-by-side
bomi analyze CXXXXX	Analyze a cached datasheet with OpenRouter
bomi datasheet CXXXXX --pdf --summary -o dir/	Download PDF and write a markdown summary
bomi datasheet --all --pdf --summary --force -o dir/	Process datasheets for all selected LCSC parts in the active project BOM
bomi init	Create .bomi/project.yaml in current directory
bomi select CXXXXX --ref U1	Add a BOM entry (fetches if not cached)
bomi deselect U1	Remove a BOM entry by reference
bomi relabel R1 R3	Rename a BOM reference
bomi list	Show the full BOM with pricing and stock (bom is an alias)
bomi list --check	Refresh BOM stock and pricing from live catalog
bomi list --format json	Export BOM as JSON
bomi status	Show project summary with cost estimate and warnings
bomi db stats	Show local cache statistics

Categories & attribute filters

Use bomi sync once (per machine/workflow) so search --category can resolve names. Browse names with bomi categories or bomi categories mosfet. For search, pick a subcategory name (not only a top-level parent) — the CLI will list children if you pass a parent.

--attr "Name operator value" works on both search and query. Combine with --category, --package, --min-stock, --max-price, --basic-only, or --preferred-only as needed. Multiple --attr flags are ANDed.

Common flows

Sync categories and search

bomi sync
bomi categories mosfet
bomi search "N-Channel" --category "MOSFETs"

Search and inspect

bomi search "buck converter 3.3V"
bomi fetch C9865
bomi info C9865
bomi compare C9865 C28023

Filter by attributes

bomi search "0402 resistor" --attr "Resistance >= 10k"
bomi search "MOSFET SOT-23" --attr "Drain Source Voltage (Vdss) >= 30"
bomi query --category "Chip Resistor" --basic-only --attr "Resistance >= 10k"
bomi query --basic-only --attr "Capacitance <= 100n"
bomi query --category "Slide Switches" --attr "Circuit = SP3T"

Attribute operators: >= <= > < = != (!= is mainly for non-numeric / string attributes). Values support SI prefixes: 10k, 100n, 4.7u. Non-numeric attributes use string equality with = or != (exact match on the raw value). Multiple --attr flags are ANDed together.

Work in a project

cd my-project
bomi init --name "My Board" --description "Description here"

bomi select C9865 --ref U3 --qty 1 --notes "3.3V buck"
bomi select C8678 --ref D3 --qty 1 --notes "catch diode"

bomi list
bomi list --check
bomi status

Work with datasheets

bomi fetch C9865
bomi analyze C9865
bomi analyze C9865 --prompt "What is the enable pin threshold voltage?"
bomi fetch --all --force
bomi datasheet --all --pdf --summary --force -o docs/datasheets/
bomi datasheet C9865 --pdf --summary -o docs/datasheets/

The analyze command sends the datasheet PDF to OpenRouter and returns structured markdown. Requires an OpenRouter API key in config. The datasheet command writes files to disk: a PDF and (with --summary) a .md alongside it.

Output format

Most commands support --format table|json|csv|markdown. JSON uses this envelope:

{
  "status": "ok",
  "command": "search",
  "count": 1,
  "results": [ ... ]
}

list --format json (and bom --format json) is different — it uses data instead of results:

{
  "status": "ok",
  "command": "bom",
  "data": [ ... ]
}

status is text-only and does not support --format.

Project context

Project context is resolved in this order:

1. --project <path>
2. BOMI_PROJECT environment variable
3. Walk up from the current directory until .bomi/project.yaml is found

bomi init also appends datasheet PDF ignore rules to .gitignore.

If running from outside the project tree (e.g. via uv run --directory), set BOMI_PROJECT to avoid needing --project on every command.

Configuration (project.yaml + global options)

Project file: .bomi/project.yaml

project.yaml is project-local and should usually be committed to git. It stores project metadata and selected parts:

name: my-board
description: Motor driver board
created: "2026-03-19"
selections:
  - ref: U3
    lcsc: C9865
    quantity: 1
    notes: 3.3V buck regulator

Core fields: name, description, created, and selections[] entries with ref, lcsc, quantity, notes (plus optional alternatives).

Global config: config.yaml

Global config lives at:

• macOS: ~/Library/Application Support/bomi/config.yaml
• Linux: ~/.local/share/bomi/config.yaml

Relevant keys:

openrouter_api_key: sk-or-v1-...
default_model: anthropic/claude-sonnet-4.6
datasheet_output_dir: docs/datasheets

How they are used:

• openrouter_api_key: required for analyze and datasheet --summary/--summarize
• default_model: default model for analyze/summaries when --model is not provided
• datasheet_output_dir: default output path for bomi datasheet when -o/--output is not provided

Environment variables override config values: BOMI_OPENROUTER_API_KEY, BOMI_DEFAULT_MODEL, BOMI_DATASHEET_OUTPUT_DIR.

Good defaults

• Run sync once before relying on search --category.
• Run fetch before info, compare, analyze, or datasheet (unless you use select, which can fetch for you).
• Use query when you want fast, offline, reproducible filtering from the local cache.
• Use list --check before ordering to refresh stock and pricing from the live catalog.
• Use one reference per BOM line when possible (R1, U2, etc.).
• Add --notes to selections to record why a part was chosen.
• Commit .bomi/project.yaml with every BOM change so decisions are tracked in git.