The CLI ships in the @webjsdev/ui package as the webjsui binary. Run it with npx @webjsdev/ui <command> from any package manager, or as webjs ui <command> inside a WebJs app, since @webjsdev/ui is a dependency of the WebJs CLI and webjs ui passes its arguments straight through.
init, add, list and view read the registry that ships inside the installed package, so they need no network. Only diff, and a custom registry passed with --registry, go to the network.
init
Use the init command to initialize configuration and dependencies for an existing WebJs app. An app created with webjs create is already initialized.
The init command writes components.json, adds the cn util at lib/utils/cn.ts (with lib/utils/dom.ts beside it) and appends the theme's CSS variables to your stylesheet, styles/globals.css by default.
Options
Usage: webjsui init [options]
Initialize @webjsdev/ui in a project: writes components.json, theme CSS,
lib/utils/cn.ts
Options:
-c, --cwd <cwd> the working directory (default: the current directory)
-y, --yes skip confirmation prompts (default: false)
--base-color <color> base color (neutral|stone|zinc|mauve|olive|mist|taupe)
--css <path> path to the project Tailwind CSS file
-o, --overwrite replace an existing alias map, existing helper files and
the theme block (default: false)
--preset <code> apply a design-system preset code from
webjs.dev/ui/create (style, colors, font, radius, icons)
--style <name> component style
(new-york|vega|nova|maia|lyra|mira|luma|sera|rhea)
--icons <library> icon library
(lucide|tabler|hugeicons|phosphor|remixicon)
--registry <url> registry base URL (default:
"https://webjs.dev/ui/registry")
-h, --help display help for command
To start from a design system, build one in Create and pass the code it prints. A preset sets the style, the colors, the radius, the fonts and the icon library in one go: it writes them to components.json, replaces the theme block in your stylesheet with the preset's tokens, writes the chosen icon library to lib/utils/icons.ts, and prints the stylesheet URL for the preset's fonts, which you load yourself. --style and --icons set one of those on their own, and also override what a preset names.
A style or icon library applies to what add writes from then on. Components you added before keep the classes they were baked with until you add them again with --overwrite.
Running init again is safe. An existing components.json keeps its aliases, stylesheet path and base color, and an existing cn.ts or dom.ts is left as you edited it. Pass --overwrite to reset them, the theme block included. A theme block written before the kit marked where it ends is never replaced, only reported, since init cannot tell where it stops. The command exits with an error when it cannot write the theme tokens, so a clean exit means the components are styled.
add
Use the add command to add components, blocks and their dependencies to your project.
It resolves each item's registry dependencies transitively, copies the source into your components/ui alias, installs any npm dependency your package.json does not already declare with your project's package manager, and puts back the theme tokens if they are missing. A block's files land at their own targets under the app. See Blocks.
Options
Usage: webjsui add [options] [components...]
Add one or more components to your project
Arguments:
components component names (e.g. button card dialog)
Options:
-c, --cwd <cwd> the working directory (default: the current directory)
-y, --yes skip overwrite prompts (default: false)
-o, --overwrite overwrite existing files without asking (default: false)
--no-deps skip installing npm dependencies
--registry <url> registry base URL (default: "https://webjs.dev/ui/registry")
-h, --help display help for command
For a class-helper component, add copies the helpers and leaves the worked example out of the file, with a one-line pointer to npx @webjsdev/ui view <name>, which prints it. The shared cn.ts and dom.ts helpers, and every file a block writes, are yours once they exist: add replaces one only with --overwrite, and --yes alone does not.
view
Use the view command to view items from the registry before installing them.
For a component it prints the projected view (the helpers with their signatures, the accessibility notes and the paste-ready example) followed by the full source. For a block it prints the description, the categories, the dependencies, the install command and every file with the path it lands at, then the sources.
Sources are printed baked with the style named in components.json, or new-york when it names none. Pass --style to see another one.
Options
Usage: webjsui view [options] <name>
Print a registry item's source (and the paste-ready example) to stdout
Arguments:
name component, block or chart name
Options:
--registry <url> registry base URL (default: "https://webjs.dev/ui/registry")
--source print only the raw source, not the projected view
--style <name> the style to bake the source with (default: components.json,
else new-york)
--json a block or chart: print the projection as one JSON document
--files-only a block or chart: print the file list and stop before the
sources
-h, --help display help for command
search
Use the search command to search for items in the registry.
The filter matches a substring of the name:
Or narrow the list to one kind of item, or to one category of blocks:
The list command is an alias for search:
Without --type it prints the components, blocks and charts in three labelled groups. --json prints one compact array of { name, type, categories, description } and nothing else, for a script or an agent.
Options
Usage: webjsui list|search [options] [filter]
List the components, blocks and charts in the registry
Arguments:
filter filter by substring of the name
Options:
--type <type> ui, block, chart or all (ui | block | chart | all)
(default: "all")
--category <name> only blocks and charts in this category (e.g. login,
sidebar, area)
--json print one compact JSON array of { name, type, categories,
description }
--registry <url> registry base URL (default:
"https://webjs.dev/ui/registry")
-h, --help display help for command
build
Use the build command to generate the registry JSON files.
This command reads the registry.json file, inlines each file's content into its item and writes one <name>.json per item to the r directory, plus an index.json and a copy of the manifest. Serve that directory and pass its URL to --registry. See Registry.
Options
Usage: webjsui build [options] [file]
Build a custom registry: read registry.json, inline file contents, emit r/*.json
Arguments:
file registry manifest path (default: "registry.json")
Options:
-o, --output <dir> output directory (default: "./r")
-c, --cwd <cwd> the working directory (default: the current directory)
-h, --help display help for command
To customize the output directory, use the --output option.
diff
Use the diff command to check your local copies against the registry.
Components are copied into your app, so an upgrade of the kit does not change them. diff is how you find the drift. It compares each file against the live registry, transformed exactly as add would write it, so an untouched install reports nothing. Installed blocks are included. With no name it lists every item that is out of date.
Options
Usage: webjsui diff [options] [name]
Show differences between local components or blocks and the registry
Arguments:
name component or block to diff (omit to show all out-of-date)
Options:
-c, --cwd <cwd> the working directory (default: the current directory)
--registry <url> registry base URL (default: "https://webjs.dev/ui/registry")
-h, --help display help for command
info
Use the info command to get information about your project.
It prints the working directory, the registry URL, the kit's component, block and chart counts, and whether a components.json was found. When one was, it adds the base color, the stylesheet path and the aliases it resolved.
Options
Usage: webjsui info [options]
Print project diagnostics (config, registry)
Options:
-c, --cwd <cwd> the working directory (default: the current directory)
-h, --help display help for command
lint
Use the lint command to check your app against its design system.
It reads the classes in your html templates, cn() calls and class=${...} holes and reports, at the line, a raw palette color where your theme declares a token (no-raw-colors), an arbitrary value such as p-[13px] (no-arbitrary-values), and a class composed over a kit helper (no-restyle). Each message names the alternative from your own theme tokens and helper variants.
The linter is opt-in. It reports nothing and exits 0 until components.json carries a lint block:
{
"lint": {
"ignore": ["app/legacy/**"],
"rules": {
"no-raw-colors": "warn",
"no-arbitrary-values": { "severity": "warn", "allow": ["layout"] },
"no-restyle": { "severity": "error", "allow": ["layout", "rounded"] }
}
}
}
It exits 1 on an error, on more warnings than --max-warnings allows, or on a config it cannot run against.
Options
Usage: webjsui lint [options]
Check the app against its design system (opt-in, configured in components.json)
Options:
-c, --cwd <cwd> the working directory (default: the current directory)
--json emit structured violations for an agent loop
--max-warnings <n> fail when warnings exceed this count (default: "-1")
-h, --help display help for command