CLI

felicityui init, add, list, info, and doctor. Diff, update, and search are reserved.

React items are TypeScript source. The CLI copies them into your tree. You own the files. There is no FelicityUI runtime to import from npm.

Native Android source-set detection and Kotlin package rewrite require CLI 0.1.6 or later. If npx felicityui still prints an older version, pin @latest.

Run

No global install. npx downloads felicityui and runs it. Node.js 22 or later.

terminal

npx felicityui@latest --version

Commands

Platform detection reads package.json / Next / Vite, Xcode / Package.swift, and Gradle Compose indicators. --platform always wins.

init

Write felicityui.json and install tokens. React also gets lib/cn.ts.

terminal

npx felicityui init --platform react

add <item>

Copy native source for the current platform. Runs init first if the config is missing.

terminal

npx felicityui add button --platform react

list

Catalog filtered by platform. Utilities stay hidden unless you add them by name.

terminal

npx felicityui list --platform react

info <item>

Spec, tokens, dependencies, and accessibility for one item.

terminal

npx felicityui info button

doctor

Node 22+, config, detection, token files, and platform wiring.

terminal

npx felicityui doctor

add

If felicityui.json is missing, add runs init first. Existing files are never overwritten unless you pass --overwrite — the CLI prints a diff and exits.

Flags

Flag	Purpose
--platform <platform>	react \| swiftui \| compose. Always wins over detection.
--overwrite	Replace local files that differ from the registry. Without it, add prints a diff and exits.
--dry-run	Print the install plan without writing files.
--skip-install	Do not install npm packages. React-only (clsx, Tailwind).
--insecure	Skip SHA-256 digest checks. Do not use this in production installs.

init flags

Flag	Purpose
--platform <platform>	react \| swiftui \| compose.
--registry <url>	Registry base URL or a local folder of compiled /r JSON.

Config

Writes felicityui.json, installs semantic tokens, and installs lib/cn.ts. Vite and Next.js --src-dir projects land under src/. On React, the CLI also installs clsx, Tailwind v4, the @ alias, and patches your CSS entry. Paths below are the defaults for React.

felicityui.json

{
  "$schema": "https://forma-web-smoky-delta.vercel.app/schema/felicityui.json",
  "platform": "react",
  "aliases": {
    "components": "src/components/ui",
    "utils": "src/lib",
    "tokens": "src/ui/tokens"
  },
  "registry": "https://forma-web-smoky-delta.vercel.app/r",
  "registries": {
    "@felicityui": "https://forma-web-smoky-delta.vercel.app/r"
  }
}

Installs to components/ui, lib/cn.ts, ui/tokens/tokens.css (prefixed with src/ when that is the app root).

Platforms

Vite and Next.js --src-dir projects land under src/. After add, the CLI installs clsx and Tailwind v4, points @ at the source root so @/lib/cn resolves, and imports tokens.css from the Tailwind entry. Do not import tokens.css from JavaScript. Restart the dev server.

Let the CLI finish the Vite project. After add, FelicityUI installs clsx and Tailwind, points @ at your source root in Vite and tsconfig, and patches the global CSS. Restart the dev server. Pass --skip-install only if you will add those packages yourself.
Import tokens.css from the Tailwind entry. Put @import "tailwindcss" and @import ".../tokens.css" in the same stylesheet (src/index.css or app/globals.css). Importing tokens.css from JavaScript raises an unknown @theme warning because @theme is only valid in the Tailwind pipeline.
If styles or @/lib/cn still fail. Run felicityui doctor. It checks clsx, Tailwind, the Vite @ alias, tsconfig paths, and that tokens.css is not imported from a JS entry.

Full walkthrough: Installation. Platform notes: React.

doctor

Checks Node 22+, felicityui.json, platform detection, and token files. Checks clsx, Tailwind, the Vite @ alias, tsconfig paths, and that tokens.css is not imported from a JS entry.

terminal

npx felicityui doctor

Reserved

felicityui diff, felicityui update, and felicityui search are reserved and not implemented in v1. Agents can read the catalog through the MCP server without writing files.