Tooling
CLI
One small command-line tool for browsing the registry and copying components, built to be pleasant for people and parseable for scripts.
Running it
The CLI is published on npm as @agents-npm-packages/vibeui. Nothing is installed globally, and npx caches the download.
npx @agents-npm-packages/vibeui --helpInside a clone of the repo, the same binary is node bin/vibeui.mjs or npm run vibeui. The examples below say vibeui for short.
Commands
| Command | What it does |
|---|---|
| list | Lists every component with category, description and dependencies. |
| search <query> | Searches names, descriptions and tags. Multiple words must all match. |
| get <name> | Shows one component's metadata, including its API. |
| add <name…> | Copies components, plus the siblings they import, into a directory. |
| init | Writes the token file, utils.ts and a short integration guide. |
| categories | Lists the shelves and how many components each holds. |
| registry | Regenerates registry/components.json from the source files. |
| guide | Prints the install guide used by agents. |
| mcp | Starts the MCP server over stdio. |
add
vibeui add <name...> [--dir <path>] [--tokens] [--no-utils]| Flag | Default | Effect |
|---|---|---|
| --dir <path> | ./src/components/ui | Where to write the component files. |
| --tokens | off | Also copy the token file to vibeui.tokens.css, three folders above --dir. |
| --no-utils | off | Skip creating src/lib/utils.ts (otherwise written if missing). |
Names are kebab-case and case-insensitive (RotatingCarousel and rotating-carousel both work). Each added file is printed with its path, and files that were only added because another component imports them are marked.
$ vibeui add footer-cta --dir ./src/components/ui
✓ footer-cta → /app/src/components/ui/footer-cta.tsx
✓ button → /app/src/components/ui/button.tsx (required by another component)
✓ spinner → /app/src/components/ui/spinner.tsx (required by another component)
✓ utils → /app/src/lib/utils.ts
Peers to install: npm i clsx tailwind-merge class-variance-authorityinit
vibeui init [--dir <path>]Creates src/components/ui/ and src/lib/, writes src/lib/utils.ts and vibeui.tokens.css if they do not exist, and always refreshes VIBEUI.md (a short guide for you or your agent). It never overwrites your existing utils or tokens.
Reading the registry
# everything in a category
vibeui list --category forms
# find by need
vibeui search "date picker"
# metadata, then source
vibeui get calendar
vibeui get calendar --sourceStructured output
Add --json to list, search, get and categories for machine-readable output. Pipe it to jq or read it from a script.
vibeui search carousel --json | jq -r '.[].name'
vibeui get dialog --json | jq '.api[0].props[] | {name, type}'Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Unknown component, missing arguments, or at least one add failed. |
In CI
Because add exits non-zero on failure, it is safe to run in a script or a bootstrap step. Pin the version for reproducible installs:
npx @agents-npm-packages/vibeui@0.8.0 add button dialog --dir ./src/components/ui