VeanUI CLI

vean is the command-line tool for VeanUI. It helps you initialize projects, add components, manage your UI configuration, and migrate a project to VeanUI.

Installation

pnpm add -D @vean/cli

Or run directly:

npx @vean/cli@latest init

Commands

vean init

Initialize a new VeanUI project or add configuration to an existing one.

vean init [options]

Interactive prompts will guide you through the configuration when no options are provided.

vean add

Add components to your project.

vean add <component...> [options]

vean build

Build registry JSON files from a registry.json manifest.

vean build [registry] [options]

vean search

Search for available components.

vean search [query] [options]

vean list

List registry items, optionally filtered by package.

vean list [options]

Items are namespaced by package (currently ui/button, ui/accordion, …; future peripheral packages follow <package>/<component>).

vean view

View a component’s source code.

vean view <component>

vean info

Show project configuration and available preset values.

vean info [options]

vean template

Scaffold a new project from a template.

vean template [name] [options]

Available templates: vue-vite, nuxt.

vean preset

Manage configuration presets.

vean preset <preset>

vean migrate

Migrate a SoybeanUI-era project — one depending on @soybeanjs/* or using the sbean CLI — to VeanUI (@vean/*).

vean migrate [migration] [options]

Available migrations: rebrand (SoybeanUI → Vean). Package specifier rewrites always apply; the runtime-contract, CLI and hostname tiers are opt-in, and --new-domain, --new-cdn and --repo-slug are independent of each other.

vean migrate rebrand                       # preview
vean migrate rebrand --write               # apply
vean migrate rebrand -w --runtime-contract --cli --new-domain veanui.com

Preflight. After scanning, the command looks for SoybeanUI-era traces: @soybeanjs/* dependencies in package.json, a sbean.json, @soybeanjs/* specifiers in source, data-soybean-* / --soybean-* contracts and sbean invocations. When none are found — the directory is wrong, or the project is already migrated — it refuses to run, exits 1 and writes nothing. A project with only old hostname links is refused too, unless you asked for a hostname rewrite explicitly. Use --force to run regardless.

Every run ends with two project-specific blocks: Worth adding (opt-in flags that still match something in the project, e.g. “12 data-soybean-* references → add --runtime-contract”) and Still manual (only the steps that apply, such as a dependency swap built from the actual package.json). Lock files, node_modules, build output and CHANGELOG.md are never rewritten, and the run is idempotent. See the brand migration guide for the complete walkthrough.

Configuration

The vean.json file stores your project configuration:

{
  "iconLibrary": "lucide",
  "uno": {
    "base": "zinc",
    "primary": "indigo",
    "size": "md",
    "radius": "md"
  },
  "font": {
    "sans": "inter",
    "heading": "inherit"
  },
  "aliases": {
    "ui": "#ui"
  },
  "registries": {}
}

Project Structure

Single Package

project/
├── src/
│   └── ui/           ← component output (uiDir)
│       ├── components/
│       ├── styles/
│       ├── theme/
│       ├── constants/
│       ├── resolver/
│       └── nuxt/
├── vean.json
├── tsconfig.json
└── uno.config.ts

Monorepo (pnpm workspaces)

project/
├── packages/
│   └── ui/           ← component output (uiDir)
│       ├── components/
│       ├── styles/
│       ├── theme/
│       ├── constants/
│       ├── resolver/
│       └── nuxt/
├── vean.json
├── tsconfig.json
├── uno.config.ts
└── pnpm-workspace.yaml

Alias System

VeanUI uses the #ui TypeScript path alias for all component imports:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "#ui/*": ["./src/ui/*"]
    }
  }
}

All component imports use this namespace:

import { SButton } from '#ui/components/button';
import { buttonVariants } from '#ui/styles/button';

Registry

Vean fetches component source from the VeanUI registry at https://veanui.com/r/<package>/<component>.json — the core ui package from r/ui/{name}.json (e.g. r/ui/button.json) and the catalog index from r/registry.json. Registry items are namespaced by package, so {name} in a registry URL template is the qualified item name (ui/button), not the bare component name. Core ui components can be referenced without a prefix (vean add button); components from any future peripheral package will require the namespace prefix (vean add <package>/<component>). A local cache (~/.vean/cache) is maintained with 24-hour TTL and ETag support for efficient updates.