@nikolas.sapa/ns-ui

CLI for the ns-ui component registry. Search and browse the catalog, read a component's props and install command, and install it via shadcn — all from the terminal.

Install

No install needed, run directly with npx:

npx @nikolas.sapa/ns-ui <command>

Commands

search

npx @nikolas.sapa/ns-ui search <query> [--category <id>] [--collection core|loud] [--limit <n>]

Searches component names, titles, descriptions, tags, and "use when" selection guidance. Every word in <query> must appear somewhere in a component's searchable text (order doesn't matter), so search "reactive hero" narrows on both words, not just one.

npx @nikolas.sapa/ns-ui search "reactive hero"
npx @nikolas.sapa/ns-ui search table --category data --limit 5

list

npx @nikolas.sapa/ns-ui list [--category <id>] [--collection core|loud]

Lists every component, grouped by category, with a count per category.

npx @nikolas.sapa/ns-ui list --category forms
npx @nikolas.sapa/ns-ui list --collection loud

info

npx @nikolas.sapa/ns-ui info <name> [--source]

Prints description, "use when" guidance, tags, categories, props, dependencies, and the install command for one component. Source is omitted by default (it's long); pass --source to also fetch and print the real component.tsx (one network request).

npx @nikolas.sapa/ns-ui info undo-ghost-row
npx @nikolas.sapa/ns-ui info undo-ghost-row --source

add

npx @nikolas.sapa/ns-ui add <name> [...names] [--dry-run]

Installs one or more components by delegating to npx shadcn@latest add https://design.helpmarq.com/r/<name>.json, once per name. An unknown name fails immediately with a "did you mean" suggestion instead of being handed to shadcn. --dry-run validates names and prints what would be installed without running shadcn.

npx @nikolas.sapa/ns-ui add undo-ghost-row
npx @nikolas.sapa/ns-ui add undo-ghost-row date-range-tape
npx @nikolas.sapa/ns-ui add undo-ghost-row --dry-run

categories

npx @nikolas.sapa/ns-ui categories

Prints the browsable category taxonomy (the same 12 categories the site's chip row uses) with a component count per category, split by collection.

mcp

npx @nikolas.sapa/ns-ui mcp

Prints the MCP client config block for the sibling @nikolas.sapa/ns-ui-mcp server, so you don't have to go find the docs to wire it up.

Every command also accepts -h/--help for command-specific usage; bare ns-ui (or -h/--help) prints the command list above. -v/--version prints the installed CLI version.

Environment variables

| Variable | Purpose | |---|---| | NS_UI_REGISTRY | Registry origin the CLI reads registry.json and llms.txt from, and the origin baked into the install commands it prints. Defaults to https://design.helpmarq.com. | | NS_UI_CACHE_TTL_MS | Lifetime of the on-disk catalog cache, in milliseconds. Defaults to 43200000 (12 hours). |

Where the data comes from

This package is fully standalone — it does not import, read, or depend on the sibling ns-ui-mcp package or its generated snapshot in any way. It has its own data path, built from the same two public files anyone can already fetch directly from the site: registry.json (names, titles, full descriptions, dependencies, tags, collection) and llms.txt (use-when guidance and condensed prop signatures). cli/lib/build-index.js merges them, and cli/lib/taxonomy.js (a deliberate, standalone copy of the category logic at lib/search-categories.ts/lib/kind.ts in this repo, not a runtime import of it) computes categories and the short "kind" label.

search, list, info, and categories resolve that merged index in three tiers, in order:

1. On-disk cache (~12h TTL, override with NS_UI_CACHE_TTL_MS) — avoids a network round trip on every invocation once warm.
2. Live fetch of registry.json + llms.txt — this is what keeps a CLI installed months ago still seeing newly added components; the cache is refreshed and used from then on.
3. The index bundled into this package at publish time (data/registry-index.json, generated by cli/scripts/build-cli-snapshot.mjs from the same two files read off disk in this repo, no mcp/ involved) — used only when there's no cache and the network is unreachable, so every command still works fully offline, just possibly stale.

add validates names against whichever tier resolves, but the actual install always goes over the network via shadcn add regardless of cache state — so add's ability to install a component is never blocked by an offline data layer, only its "did you mean" suggestion quality is. info --source is a fourth, separate network call: it fetches the real component.tsx from the live registry on demand rather than bundling every component's source into the index.

Links

• Registry
• MCP server — the same catalog as tools for an agent, not a human (a separate package, no code shared with this CLI)
• Source