CLI reference

The lorre-blocks CLI ships on npm. Every command below also takes --json: one JSON document on stdout, no prompts, ever.

Command	What it does
init [--theme <name>] [-y]	Write components.json, install base deps, inject the theme.
add <names...> [-o]	Copy components (and their registry dependencies) into your project.
list	List every registry item.
search <query> [--category] [--source]	Rank registry items against a query plus facet filters.
info <name> [--files]	One item's metadata, dependencies and target paths.
diff [names...]	Compare your local copies against the registry; with lorre.lock it reports who changed each file (local edits, registry update, or diverged).
update [names...] [-f]	Pull registry updates. Rewrites only files you have not edited (per lorre.lock); diverged files need --force.
theme list / theme apply [name]	Inspect and swap themes. Without a name, apply regenerates from lorre.theme.json.
theme create [--from <file>] [flags]	Create a custom theme: colors (hex or OKLCH), fonts, type scale, radius, scaling, component tokens, icon set. Generates the CSS locally and injects it.
theme show	Print the active theme's resolved design system (scales, semantics, type scale, component tokens).
plan check <plan.json>	Validate a plan and resolve it against the registry (read-only). The plan's theme may be an inline custom definition.
apply <plan.json> [-o]	Execute a plan: theme + token overrides + items in one run.

For agents

--json is the machine contract: pick components by searching, inspect before installing, then add — all without a TTY.

npx lorre-blocks search "date input" --category component --json

npx lorre-blocks info date-picker --json

npx lorre-blocks add date-picker --yes --json

npx lorre-blocks theme create --from lorre.theme.json --json

npx lorre-blocks theme show --json

To build a full design system, write a lorre.theme.json (see Theming) and run theme create — validation problems come back as one flat JSON list.

Registry endpoints

Everything the CLI reads is plain static JSON — usable directly.

/r/index.json            all items with metadata + checksums
/r/manifest.json         schema version + facet summaries
/r/<name>.json           one item, file contents included
/r/themes/index.json     available themes
/r/themes/<name>.json    a theme's Tailwind v4 CSS
/r/tokens/<name>.json    the same theme as W3C DTCG tokens
/r/icons/index.json      supported icon sets (package, styles, license)