CLI Support

Use the vayu-ui CLI to initialize, add, update, and remove components and hooks in your React project.

The vayu-ui CLI lets you scaffold Vayu UI into any React project with a copy-paste approach — you own the code, no runtime dependency required.

Quick Start

1. Create a new project with Vayu UI (Next.js or Vite)

npx vayu-ui-cli@latest create my-app

2. Initialize Vayu UI in an existing project

npx vayu-ui-cli@latest init

3. Browse what's available

npx vayu-ui-cli@latest list

4. Add a component or hook

npx vayu-ui-cli@latest add button

No installation needed — npx runs the latest version directly.

`vayu-ui create <name>`

Scaffolds a brand new React project with Vayu UI pre-configured. Supports Next.js and Vite.

npx vayu-ui-cli@latest create my-app

npx vayu-ui-cli@latest create my-app --framework next --force

npx vayu-ui-cli@latest create my-app --framework vite --skip-init

What it does:

Scaffolds a fresh Next.js or Vite project using bundled, tested templates
Initializes Vayu UI automatically (unless --skip-init)
Adds starter components: Button, Typography, Select, useLocalStorage, useDebounce, useOnClickOutside, plus their required hooks and utilities
Installs all npm dependencies automatically

Flags:

Flag	Description
`--framework <next\|vite>`	Framework to scaffold (default: next)
`--package-manager <npm\|pnpm\|yarn\|bun>`	Package manager (default: auto-detect)
`--app-router`	Use App Router (Next.js only, default: true)
`--no-app-router`	Use Pages Router (Next.js only)
`--typescript`	Use TypeScript (default: true)
`--no-typescript`	Use JavaScript
`--tailwind`	Include Tailwind CSS (default: true)
`--no-tailwind`	Skip Tailwind CSS
`--eslint`	Include ESLint (default: true)
`--no-eslint`	Skip ESLint
`--src-dir`	Use `src/` directory (default: true)
`--no-src-dir`	Don't use `src/` directory
`--skip-init`	Skip Vayu UI initialization after scaffolding
`--skip-install`	Skip npm install during scaffolding
`--force`	Skip all prompts, use defaults

`vayu-ui init`

Sets up Vayu UI in your project. Creates the folder structure, injects design tokens as CSS, and optionally installs Tailwind CSS v4.

npx vayu-ui-cli@latest init

What it does:

Detects your framework (Next.js, Vite, CRA, or generic)
Creates ui/components/, ui/hooks/, ui/utils/ (inside src/ if it exists)
Creates vayu-ui-tokens.css with all design tokens next to your main CSS
Adds @import to your existing CSS file
Prompts to install Tailwind CSS v4 if not found
Creates vayu-ui.config.json to track paths and installed items

Flags:

Flag	Description
`--path <dir>`	Custom path for the ui/ folder (default: auto-detect `src/ui` or `ui`)
`--css-path <file>`	Custom path for the main CSS file
`--merge`	Merge tokens into existing CSS instead of creating a separate file
`--skip-tailwind`	Skip Tailwind CSS installation check
`--force`	Skip all prompts and use defaults

npx vayu-ui-cli@latest init --merge

npx vayu-ui-cli@latest init --path src/lib/ui

npx vayu-ui-cli@latest init --skip-tailwind

`vayu-ui list`

Displays all 59 components and 34 hooks available in the Vayu UI registry, grouped by type and category.

npx vayu-ui-cli@latest list

Flags:

Flag	Description
`--type <component\|hook>`	Filter by item type
`--category <name>`	Filter by category (e.g. `inputs`, `state`)

npx vayu-ui-cli@latest list --type hook

npx vayu-ui-cli@latest list --type component --category overlay

npx vayu-ui-cli@latest list --category sensor

`vayu-ui add <slugs...>`

Copies one or more components or hooks from the installed CLI release into your project. Automatically resolves transitive dependencies and installs required npm packages.

npx vayu-ui-cli@latest add button

npx vayu-ui-cli@latest add button modal tooltip

npx vayu-ui-cli@latest add use-debounce use-local-storage

What it does:

Looks up each slug in the registry
Recursively resolves dependencies (e.g. sidebar → tooltip)
Copies bundled source files
Writes them into {uiPath}/components/{Name}/ or {uiPath}/hooks/
Auto-includes the cn utility (utils/index.ts) when adding any component
Installs npm packages (clsx, tailwind-merge, lucide-react, etc.)
Records installed items in vayu-ui.config.json

Flags:

Flag	Short	Description
`--overwrite`	`-o`	Overwrite existing files
`--dry-run`	—	Preview what would be added without writing
`--skip-install`	—	Skip npm dependency installation
`--yes`	`-y`	Skip confirmation prompts

npx vayu-ui-cli@latest add modal --dry-run

npx vayu-ui-cli@latest add button --overwrite

npx vayu-ui-cli@latest add sidebar --skip-install

After installing, import components from your ui folder:

import { Button } from '@/ui/components/Button';
import { useDebounce } from '@/ui/hooks/useDebounce';

`vayu-ui update [slugs...]`

Refreshes installed components and hooks from the installed CLI release. Compares file contents and only overwrites changed files.

npx vayu-ui-cli@latest update

npx vayu-ui-cli@latest update button modal

Flags:

Flag	Short	Description
`--force`	`-f`	Overwrite changed files (the default update behavior)
`--dry-run`	—	Preview what would be updated without writing files
`--css`	—	Also update Vayu UI CSS design tokens

npx vayu-ui-cli@latest update --dry-run

npx vayu-ui-cli@latest update --force

`vayu-ui remove <slugs...>`

Removes one or more installed components or hooks. Warns if other installed items depend on what you are removing. Auto-cleans utils/ when no components remain.

npx vayu-ui-cli@latest remove button

npx vayu-ui-cli@latest remove button modal

Flags:

Flag	Short	Description
`--force`	`-f`	Skip confirmation prompt

npx vayu-ui-cli@latest remove use-debounce --force

Configures the Vayu UI MCP server for AI coding tools. The server exposes 17 tools for component discovery, props, variants, scaffolding, and design tokens — so your AI assistant can work with Vayu UI natively.

No local installation needed — the server runs via npx vayu-ui-mcp using stdio transport.

npx vayu-ui-cli@latest install-mcp

npx vayu-ui-cli@latest install-mcp --tool claude

npx vayu-ui-cli@latest install-mcp --tool claude,cursor,vscode

Supported tools:

Tool	Project-level config	Global config
Claude Code	`.claude/settings.json`	`~/.claude/settings.json`
Cursor	`.cursor/mcp.json`	`~/.cursor/mcp.json`
VS Code Copilot	`.vscode/mcp.json`	`~/.vscode/mcp.json`
Windsurf	`.windsurf/mcp.json`	`~/.windsurf/mcp.json`

What it does:

Detects or prompts for which AI tools to configure
Writes the MCP server entry to each tool's config file
Creates parent directories if needed
Skips if already configured (use --force to overwrite)

Flags:

Flag	Description
`--tool`	Comma-separated: `claude`, `cursor`, `vscode`, `windsurf`
`--global`	Write to home directory instead of project root
`--dry-run`	Preview changes without writing
`--force`	Skip prompts and overwrite existing entries

npx vayu-ui-cli@latest install-mcp --global

npx vayu-ui-cli@latest install-mcp --dry-run

npx vayu-ui-cli@latest install-mcp --tool claude --force

After running, restart your AI tool. The MCP server provides 17 tools including list_components, get_component_props, scaffold_component_usage, get_design_tokens, and more.

`vayu-ui version`

Shows the current CLI version, platform, and Node.js version.

npx vayu-ui-cli@latest version

npx vayu-ui-cli@latest v

Configuration

vayu-ui init creates a vayu-ui.config.json at your project root:

{
  "version": 1,
  "uiPath": "src/ui",
  "cssFile": "src/app/globals.css",
  "tokensFile": "src/app/vayu-ui-tokens.css",
  "installed": {
    "button": {
      "type": "component",
      "installedAt": "2026-04-19T12:00:00.000Z"
    }
  }
}

The CLI uses this file to:

Know where to write files when you run add
Track which items are installed for update and remove
Store your CSS file path for token injection

Folder Structure

After running vayu-ui init, your project gets a ui/ folder (or src/ui/ if you use a src/ directory):

src/ui/
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── ButtonIcon.tsx
│   │   ├── ButtonBadge.tsx
│   │   ├── ButtonText.tsx
│   │   ├── types.ts
│   │   └── index.ts
│   └── Modal/
│       └── ...
├── hooks/
│   ├── useDebounce.ts
│   └── useLocalStorage.ts
└── utils/
    └── index.ts          # cn() utility (clsx + tailwind-merge)

This structure mirrors the internal packages/ui/src/ layout, so relative imports between files (like ../../utils) work without any path aliases.

Stable source generation and workspaces

The CLI ships its component sources with the package. add and update use the same source dependency graph, including shared utilities. Updating to another release means running npx vayu-ui-cli@latest update. Local changes can be overwritten by update; preview with --dry-run first.

npx vayu-ui-cli@latest add --all --yes
npx vayu-ui-cli@latest add modal --cwd apps/web --yes
npx vayu-ui-cli@latest update --dry-run
npx vayu-ui-cli@latest update --css
npx vayu-ui-cli@latest remove modal --dry-run
npx vayu-ui-cli@latest create workspace --framework next --turbo
npx vayu-ui-cli@latest create workspace --framework vite --turbo --package-manager pnpm

--turbo creates apps/web, a shared packages/ui source package, workspace manifests, Turbo tasks, and CSS scanning for the shared sources. Next.js transpiles @repo/ui; both framework starters import its exported component paths.

--skip-install writes complete dependencies and configuration without running a package manager. Run your package manager's install command once when ready. --no-typescript creates JavaScript application files; copied Vayu primitives remain TypeScript, which both supported bundlers compile. --no-src-dir, --no-eslint, --no-tailwind, and --no-app-router are supported. Without Tailwind, Vayu's utility classes require your own styling setup.

Custom folder layouts

All configured paths are relative to the directory containing vayu-ui.config.json. The nearest config is used when executing from a nested directory; --cwd selects another project. A workspace root can own a shared package:

{
  "$schema": "https://vayu.design/schema/config.json",
  "version": 1,
  "uiPath": "packages/ui/src",
  "packagePath": "packages/ui",
  "aliases": {
    "components": "@repo/ui/components",
    "hooks": "@repo/ui/hooks"
  },
  "cssFile": "apps/web/src/app/globals.css",
  "tokensFile": "packages/ui/src/styles.css",
  "installed": {}
}

For an existing app with separate directories, set paths.components, paths.hooks, and paths.utils, for example src/components/ui, src/hooks, and src/lib/vayu. The CLI rewrites relative source imports between those locations. packagePath selects the package receiving npm dependencies. aliases describe existing resolver aliases for MCP import guidance; they do not create TypeScript or bundler aliases.

Paths cannot escape the config directory. Put a shared workspace config at the workspace root instead of using ../ to target another package.

CLI Support

Quick Start

`vayu-ui create <name>`

`vayu-ui init`

`vayu-ui list`

`vayu-ui add <slugs...>`

`vayu-ui update [slugs...]`

`vayu-ui remove <slugs...>`

`vayu-ui install-mcp`

`vayu-ui version`

Configuration

Folder Structure

Stable source generation and workspaces

Custom folder layouts

On this page

CLI Support

Quick StartCopy Anchor Link

vayu-ui create <name>Copy Anchor Link

vayu-ui initCopy Anchor Link

vayu-ui listCopy Anchor Link

vayu-ui add <slugs...>Copy Anchor Link

vayu-ui update [slugs...]Copy Anchor Link

vayu-ui remove <slugs...>Copy Anchor Link

vayu-ui install-mcpCopy Anchor Link

vayu-ui versionCopy Anchor Link

ConfigurationCopy Anchor Link

Folder StructureCopy Anchor Link

Stable source generation and workspacesCopy Anchor Link

Custom folder layoutsCopy Anchor Link

On this page

Quick Start

`vayu-ui create <name>`

`vayu-ui init`

`vayu-ui list`

`vayu-ui add <slugs...>`

`vayu-ui update [slugs...]`

`vayu-ui remove <slugs...>`

`vayu-ui install-mcp`

`vayu-ui version`

Configuration

Folder Structure

Stable source generation and workspaces

Custom folder layouts