# CLI

Use the WebJs UI CLI to add components and blocks to your project.

Source: https://webjs.dev/ui/docs/cli

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.

```bash
npx @webjsdev/ui init
```

**Options**

```bash
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](https://webjs.dev/ui/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.

```bash
npx @webjsdev/ui init --preset <code>
```

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.

```bash
npx @webjsdev/ui add [component]
```

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](https://webjs.dev/ui/docs/blocks).

**Options**

```bash
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.

```bash
npx @webjsdev/ui view [item]
```

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.

```bash
npx @webjsdev/ui view login-03 --files-only
```

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**

```bash
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.

```bash
npx @webjsdev/ui search [filter]
```

The filter matches a substring of the name:

```bash
npx @webjsdev/ui search menu
```

Or narrow the list to one kind of item, or to one category of blocks:

```bash
npx @webjsdev/ui search --type block --category login
```

The `list` command is an alias for `search`:

```bash
npx @webjsdev/ui list --type block
```

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**

```bash
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.

```bash
npx @webjsdev/ui build
```

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](https://webjs.dev/ui/docs/registry).

**Options**

```bash
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.

```bash
npx @webjsdev/ui build --output ./public/r
```

---

## diff

Use the `diff` command to check your local copies against the registry.

```bash
npx @webjsdev/ui diff [component]
```

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**

```bash
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.

```bash
npx @webjsdev/ui info
```

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**

```bash
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.

```bash
npx @webjsdev/ui lint
```

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:

```json title="components.json"
{
  "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**

```bash
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
```
