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

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

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

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

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

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 for the client setup.

tokens build

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

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