# CLI

The CLI is published on npm as `werewolf-ui`; this page describes `0.1.0-alpha.1`. Run every command from your app as `npx werewolf-ui <command>`. Do not use `npx wolf`: that runs an unrelated package.

## Commands

| Command | What it does | Writes files |
| --- | --- | --- |
| `init` | Seed, token stylesheet, CSS import and agent rules | Yes |
| `add <name...>` | Component source and its dependencies | Yes, and runs the package manager |
| `theme` | Changes seed choices and regenerates the stylesheet | Seed and stylesheet |
| `lint [paths...]` | Static styling checks, optional safe fixes | Only with `--fix` |
| `mcp` | Local MCP server with five read-only tools | Never |
| `tokens build` | Exports tokens for one platform | Under `--out` |
| `docs [component]` | Prints the docs URL and opens it in a terminal | Never |

### init

```bash
npx werewolf-ui init
npx werewolf-ui init --cwd ./apps/web --package-manager pnpm
npx werewolf-ui init --agent claude,copilot
```

Sets up an app once. Creates `werewolf.json` and the seed only if they are missing, writes the token stylesheet, adds one import after your Tailwind import, and installs the agent rules. A repeat run with no changes writes nothing.

| Option | Value |
| --- | --- |
| `--css` | The app stylesheet that imports Tailwind |
| `--seed` | Seed path. Default `tokens/seed.json` |
| `--output` | Generated stylesheet. Default `styles/werewolf.css` |
| `--package-manager` | `npm`, `pnpm`, `yarn` or `bun`, when there is no lockfile or they disagree |
| `--agent` | `claude`, `copilot`, `windsurf`, `gemini`, `cline`, `cursor`, `codex`, `jules`, `amp`, `other` or `all`, as a comma list |

### add

```bash
npx werewolf-ui add button input dialog
npx werewolf-ui add button --overwrite src/components/ui/button.tsx
```

Requires init. Resolves registry dependencies, installs missing npm packages first, maps imports to your aliases, then writes the files. Identical files are skipped; a differing file conflicts until you pass its path to `--overwrite`.

### theme

```bash
npx werewolf-ui theme --accent "<hex>" --gray-tint 0.25 --radius-base round
```

Changes only the choices you pass and regenerates the stylesheet. Both modes must pass every contrast check before anything is written.

| Option | Value |
| --- | --- |
| `--accent` | A 3 or 6 digit hex color |
| `--gray-tint` | A number from 0 to 1 |
| `--radius-base` | `sharp`, `default`, `round`, `pill`, or a px value such as `6px` |

### lint

```bash
npx werewolf-ui lint
npx werewolf-ui lint src --fix
```

Checks `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs` and `.css` files, up to 500 files and 1 MiB per file. Paths are project-relative files or folders, without globs. It installs nothing and works before init too. `--fix` applies only exact edits and reanalyzes before writing.

### mcp

```bash
npx werewolf-ui mcp --cwd ./my-app
```

Starts the local MCP server over stdio for a client to launch. Any existing directory works. See [AI agents and MCP](https://www.werewolf-ui.dev/docs/agents.md) for the client setup.

### tokens build

```bash
npx werewolf-ui tokens build --out exported-tokens
npx werewolf-ui tokens build --platform android --out exported-tokens
```

Requires init. Exports `json/dark.json` and `json/light.json` plus one platform's files, without changing the seed.

| Option | Value |
| --- | --- |
| `--platform` | `web` (default), `ios` or `android` |
| `--out` | Required. A directory inside the project |

### docs

```bash
npx werewolf-ui docs
npx werewolf-ui docs date-picker
```

Prints a component's page URL, or the installation page without a name. It opens a browser only in an interactive terminal without `--json`. The site describes its latest version, which can differ from your installed CLI.

## Options for every command

- `--help` prints every command; `<command> --help` prints only that command.
- `--yes` is accepted everywhere. No command prompts, and `--yes` never authorizes an overwrite.
- `--json` prints exactly one result document on stdout and nothing else: `schemaVersion`, `command`, `ok`, `data` and `diagnostics`.
- `--cwd <path>` selects the app. Options take one value each, as `--cwd ./apps/web`, not `--cwd=./apps/web`.
- `--overwrite <path>` replaces one exact generated file after you review it. It is the only option you can repeat.

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Success. Lint found no errors, though warnings may remain. |
| 1 | Operational failure: a conflict, a write or install failure. Lint found errors. |
| 2 | Invalid arguments, an unknown component, an invalid seed, or an unsupported or ambiguous project. |
| 130 | Cancelled. |

## Conflicts and overwrites

- The CLI records what it generated in `.werewolf/managed.json`. Unchanged generated files update; files you edited return `WW_CONFLICT` with their exact path, and nothing is written.
- `--overwrite` selects only generated output, components in the current request or exported files. It can never select your seed, `werewolf.json`, your app stylesheet or `AGENTS.md`.
- File writes roll back on failure. Package installs are not rolled back.

## Diagnostic codes

Messages are in English and may change; codes are stable. [Troubleshooting](https://www.werewolf-ui.dev/docs/troubleshooting.md) explains the common ones.

| Code | Exit | Meaning |
| --- | --- | --- |
| `WW_ARGUMENT` | 2 | Unknown, missing, repeated or malformed option or value. |
| `WW_ASSETS` | 1 | The packaged catalog is missing, unreadable or invalid. Reinstall the package. |
| `WW_CANCELLED` | 130 | Lint or a file transaction was cancelled. No clean result is available. |
| `WW_CLASS_REMOVED` | lint error | A palette utility that the system does not generate. |
| `WW_COLOR_LITERAL` | lint error | A hardcoded color where a semantic color token is required. |
| `WW_COMMAND` | 2 | Unknown command or unsupported top-level arguments. |
| `WW_COMPONENT` | 2 | Unknown component name. |
| `WW_CONFLICT` | 1 | A file differs from what the CLI expects, or changed during the command. |
| `WW_CSS_IMPORT` | 2 | The app stylesheet is missing or malformed, or its styling and theme imports are missing, duplicated or misplaced. |
| `WW_CURSOR` | 2 | A pagination cursor is invalid, stale or from different filters (MCP). |
| `WW_DARK_VARIANT` | lint error | A `dark:` variant; tokens switch with `data-theme`. |
| `WW_DEPENDENCY` | 2 | Invalid dependency spec or unsupported package manager. |
| `WW_DEPENDENCY_CONFLICT` | 2 | Requested and declared dependency versions disagree. |
| `WW_DYNAMIC` | lint warning | A style expression that cannot be resolved statically. |
| `WW_ENCODING` | lint error, or 1 | A source file is not valid UTF-8; fixes are not applied in that run. An ignore file that is not valid UTF-8 stops lint with exit 1. |
| `WW_FIX_INVALID` | 1 | Proposed fixes are invalid or cannot be fully reanalyzed. Nothing was written. |
| `WW_FIX_OVERLAP` | 1 | Proposed fixes overlap. Nothing was written. |
| `WW_FIX_PARSE` | 1 | A fix would introduce a parse failure. Nothing was written. |
| `WW_IMPORT` | 2 | Component source imports cannot be parsed or mapped to the app's aliases. |
| `WW_INSTALL` | 1 | The package manager failed or its launcher cannot be resolved. No component files were committed. |
| `WW_INTERNAL` | none | An MCP tool could not complete or produced an invalid result. |
| `WW_IO` | 1 | An unexpected filesystem or runtime error. |
| `WW_LIMIT` | lint error, or 1 | A file, file count or traversal limit was exceeded. An ignore file over 1 MiB stops lint with exit 1. MCP returns it for oversized input. |
| `WW_NOT_INITIALIZED` | 1 | The app has no `werewolf.json`, seed or ownership record. Run `npx werewolf-ui init --yes`. |
| `WW_OPACITY` | lint error | A color with alpha, or an opacity outside the role tokens. |
| `WW_OPEN` | 0 (warning) | The docs URL could not be opened in a browser. Open it yourself. |
| `WW_PARSE` | lint error | A source file cannot be parsed. Its styles were not checked. |
| `WW_PATH` | 2 | A path is absolute, escapes the project, crosses a symlink or changed its target. |
| `WW_PLATFORM` | 2 | `--platform` is not `web`, `ios` or `android`. |
| `WW_PROJECT_ALIAS` | 2 | Compiler aliases are missing, ambiguous or disagree with `werewolf.json`. |
| `WW_PROJECT_AMBIGUOUS` | 2 | A workspace root, several frameworks, stylesheets or lockfiles, or a lockfile that disagrees with `packageManager`. Select explicitly. |
| `WW_PROJECT_CONFIG` | 2 | `werewolf.json` or a compatible registry config is invalid. |
| `WW_PROJECT_ROOT` | 2 | No app `package.json` at the selected directory. |
| `WW_PROJECT_VERSION` | 2 | Node, React or the styling framework version is unsupported or undeclared. |
| `WW_PROTOCOL` | 1 | MCP input or output failed; the connection is closed. |
| `WW_SEED` | 2 | The seed is malformed or a choice is out of range. |
| `WW_SIZE` | lint error | A control height outside the element size tokens, or a per-breakpoint size. |
| `WW_SOLID_PAIR` | lint error | An on-solid text or icon token paired with a different fill. |
| `WW_SPACING` | lint error | Numeric or arbitrary spacing where a spacing token is required. |
| `WW_SYMLINK` | lint warning | A symbolic link was skipped during traversal. |
| `WW_TOKEN_PROPERTY` | lint error | A real token used for a property it does not supply. |
| `WW_TOKEN_UNKNOWN` | lint error | A token name that does not exist. |
| `WW_TRUNCATED` | 1 (lint) | The diagnostic limit was reached; rerun on fewer files. |
| `WW_WRITE` | 1 | A file transaction failed. Retained backup paths are listed if rollback was incomplete. |
| `WW_WRITE_PLAN` | 2 | `--overwrite` names a path this command does not manage, or an internal write plan is invalid. |