CLI

The vinyaas package on npm (v1.5.0) installs UI as editable source. Framework create-app flows live on Installation.

What the CLI is

Vinyaas is registry-driven. The CLI copies component source into your project, installs missing npm dependencies, and leaves the files editable. Configuration for aliases and Tailwind paths lives in components.json. Framework-specific scaffolding is covered under Installation.

Install the CLI

Install globally (recommended), then invoke vinyaas <command>. Or run once with npx / pnpm dlx / yarn dlx / bunx. Requires Node.js 20+.

npm install -g vinyaas

bash

vinyaas --version

Setup

init

Run from the project root. vinyaas init detects the framework when possible, finds a CSS entry, and creates components.json, theme tokens, aliases, and utils when missing. It is safe to re-run: it does not overwrite an existing components.json or utils file. Existing shadcn-style projects can keep their layout and run init only when Vinyaas config is needed.

bash

vinyaas init

bash

vinyaas init --yes

npx vinyaas init

Options

Usage: vinyaas init [options]Prepare a React project for Vinyaas (Tailwind v4, theme CSS, aliases,components.json).Options:  --cwd <path>  Consumer project directory.  -y, --yes     Skip prompts and use safe defaults.  -h, --help    display help for command

doctor

vinyaas doctor validates an existing project without writing files. Use it after init, before adding components, or when installs fail. It reports grouped checks and suggested fixes; it does not apply fixes automatically.

bash

vinyaas doctor

bash

vinyaas doctor --json

Groups:

Project — components.json, aliases, utils.
Styling — Tailwind v4, global CSS, theme tokens.
Dependencies — clsx, tailwind-merge, tailwindcss, and @tailwindcss/postcss when applicable.
Registry — configured registry URL and reachability.

text

✓ Vinyaas doctor

Project
  ✓ components.json
  ✓ aliases configured
  ✓ utils file found

Styling
  ✓ Tailwind v4
  ✓ global CSS
  ✓ theme tokens

Dependencies
  ✓ clsx
  ✓ tailwind-merge
  ✓ tailwindcss
  ✓ @tailwindcss/postcss

Registry
  ✓ https://vinyaas.vercel.app/r

No issues found.

npx vinyaas doctor

Options

Usage: vinyaas doctor [options]Validate an existing Vinyaas project setup.Options:  --cwd <path>  Consumer project directory.  --json        Print machine-readable JSON to stdout.  -h, --help    display help for command

Install

add

Copies registry source into components/ui/<name>/. Files stay editable. Registry dependencies resolve automatically; only missing npm packages are installed. Successful installs update .vinyaas/manifest.json.

bash

vinyaas add button

bash

vinyaas add button card badge

bash

vinyaas add button card --yes

npx vinyaas add button

Options

Usage: vinyaas add [options] [name...]Add one or more components from the Vinyaas registry.Arguments:  name                   Component names to installOptions:  --cwd <path>           Consumer project directory.  --force                Overwrite existing component files instead of skipping                         them.  --dry-run              Resolve the install plan and print it without writing                         files or installing packages.  --catalog <catalog>    Install every component in a named registry catalog.  --category <category>  Install every component in a registry category.  -y, --yes              Skip confirmation prompts.  -h, --help             display help for command

Catalog installation

Catalog installs require an explicit --catalog option. Catalogs are owned by the registry (see Catalogs). The CLI lists the members, asks for confirmation with [Y/n] (default Yes), and only then installs through the same component pipeline. Pass --yes to skip the prompt. Declining cancels with no file changes. A bare vinyaas add form never installs a catalog — it looks for a component named form and, if missing, suggests --catalog form.

bash

vinyaas add --catalog form

bash

vinyaas add --catalog dashboard --dry-run

bash

vinyaas add --catalog application --yes

--force

Already-installed components are skipped by default. Pass --force to overwrite existing component files with registry content.

bash

vinyaas add button --force

--dry-run

Resolves the install plan and prints components, files, npm dependencies, and registry dependencies without writing files, installing packages, or updating the manifest. Works with named components, catalogs, and categories.

bash

vinyaas add button --dry-run

bash

vinyaas add --catalog dashboard --dry-run

bash

vinyaas add --category forms --dry-run

Category installation

Categories are registry metadata for discovery and group install. They are not component collections or packages. Category expansion feeds the same install pipeline as named components.

bash

vinyaas add --category forms

bash

vinyaas add --category forms --yes

Current categories: forms, layout, navigation, feedback, data-display, typography, charts, utilities.

Multi-component and category installs prompt for confirmation unless you pass --yes.
Explicit component names take precedence: vinyaas add button --category forms installs only button and ignores --category.
Unknown categories fail and list the available names.

update / upgrade

Overwrites installed components with the latest registry source. upgrade is an alias of update. With no names it updates every component recorded in the manifest after a confirmation. Pass names to update only those components.

bash

vinyaas upgrade

bash

vinyaas upgrade button card

bash

vinyaas update button --dry-run

Local edits to the updated files are replaced. The confirmation warns about this; skip it with --yes.
Only components installed through Vinyaas (recorded in .vinyaas/manifest.json) can be updated.
--dry-run prints the plan without writing files.

npx vinyaas update

Options

Usage: vinyaas update|upgrade [options] [name...]Update installed components to the latest registry versions (alias: upgrade).Arguments:  name          Component names to update. Omit to update every installed                component.Options:  --cwd <path>  Consumer project directory.  --dry-run     Resolve the update plan and print it without writing files.  -y, --yes     Skip confirmation prompts.  -h, --help    display help for command

status

Shows components recorded locally after successful installs. Vinyaas tracks installed components so vinyaas update can refresh them.

bash

vinyaas status

bash

vinyaas status --json

npx vinyaas status

Options

Usage: vinyaas status [options]Show components installed by Vinyaas in this project.Options:  --cwd <path>  Consumer project directory.  --json        Print machine-readable JSON to stdout.  -h, --help    display help for command

Discover

Browse without writing files. Use list to scan components, catalog for named groups, search to find by name or description, and info to inspect one component before installing.

bash

vinyaas catalog list

bash

vinyaas catalog info form

bash

vinyaas list

bash

vinyaas list --category forms

bash

vinyaas search button

bash

vinyaas search input --category forms

bash

vinyaas info button

catalog info shows membership and which members are already installed when a project manifest is available. Component list / search output can include category, description, docs URL, files, and dependencies. Filter with --category.

npx vinyaas catalog list

catalog options

Usage: vinyaas catalog [options] [command]List and inspect named component catalogs from the registry.Options:  -h, --help                display help for commandCommands:  list [options]            List available component catalogs.  info [options] <catalog>  Show details for one component catalog.  help [command]            display help for command

npx vinyaas list

list options

Usage: vinyaas list [options]List installable components from the Vinyaas registry.Options:  --json                 Print machine-readable JSON to stdout.  --category <category>  Filter components by registry category.  -h, --help             display help for command

npx vinyaas search button

search options

Usage: vinyaas search [options] <query>Search registry components by name or description.Arguments:  query                  Search queryOptions:  --json                 Print machine-readable JSON to stdout.  --category <category>  Limit search to a registry category.  -h, --help             display help for command

npx vinyaas info button

info options

Usage: vinyaas info [options] <component>Show registry details for a component before installing it.Arguments:  component   Component nameOptions:  --json      Print machine-readable JSON to stdout.  -h, --help  display help for command

JSON output

Discovery, doctor, and status accept --json for machine-readable stdout.

bash

vinyaas list --json

bash

vinyaas search input --json

bash

vinyaas info button --json

bash

vinyaas doctor --json

bash

vinyaas status --json

Errors and safety

Existing component files are skipped unless --force.
--dry-run never mutates the project or the manifest.
Category and multi-component installs confirm before writing unless --yes is set.
Failed installs roll back snapshotted project files (including package lockfiles and the install manifest when they were part of the mutation).

Registry

The CLI reads a registry catalog, then individual component items (metadata and source files). Items may include name, type, description, category, files, dependencies, registry dependencies, and docs. Override the registry root with REGISTRY_BASE_PATH (preferred) or legacy REGISTRY_BASE_URL.

bash

REGISTRY_BASE_PATH=https://vinyaas.vercel.app/r vinyaas list

Version

Print the installed CLI version (currently v1.5.0).

bash

vinyaas --version