CLI

CLI có trên npm với tên werewolf-ui; trang này mô tả bản 0.1.0-alpha.1. Chạy mọi lệnh trong app dưới dạng npx werewolf-ui <lệnh>. Đừng dùng npx wolf: lệnh đó chạy một package không liên quan.

Các lệnh

Lệnh	Làm gì	Ghi file
`init`	Seed, stylesheet token, CSS import và luật cho agent	Có
`add <name...>`	Mã nguồn component và dependency	Có, và chạy package manager
`theme`	Đổi lựa chọn trong seed và tạo lại stylesheet	Seed và stylesheet
`lint [paths...]`	Kiểm tra style tĩnh, có thể tự sửa an toàn	Chỉ khi có `--fix`
`mcp`	MCP server chạy local với năm công cụ chỉ đọc	Không bao giờ
`tokens build`	Xuất token cho một nền tảng	Trong `--out`
`docs [component]`	In URL tài liệu và mở nó trong terminal	Không bao giờ

init

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

Thiết lập app một lần. Chỉ tạo werewolf.json và seed nếu chưa có, ghi stylesheet token, thêm một dòng import sau import Tailwind, và cài luật cho agent. Chạy lại khi không có gì đổi thì không ghi gì.

Tùy chọn	Giá trị
`--css`	Stylesheet của app có import Tailwind
`--seed`	Đường dẫn seed. Mặc định `tokens/seed.json`
`--output`	Stylesheet được tạo. Mặc định `styles/werewolf.css`
`--package-manager`	`npm`, `pnpm`, `yarn` hoặc `bun`, khi không có lockfile hoặc thông tin không khớp
`--agent`	`claude`, `copilot`, `windsurf`, `gemini`, `cline`, `cursor`, `codex`, `jules`, `amp`, `other` hoặc `all`, phân cách bằng dấu phẩy

add

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

Cần init trước. Giải quyết dependency trong registry, cài package npm còn thiếu trước, ánh xạ import theo alias, rồi mới ghi file. File giống hệt được bỏ qua; file khác nội dung báo xung đột cho tới khi bạn truyền đường dẫn của nó vào --overwrite.

theme

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

Chỉ đổi những lựa chọn bạn truyền vào và tạo lại stylesheet. Cả hai chế độ phải qua mọi kiểm tra tương phản trước khi ghi.

Tùy chọn	Giá trị
`--accent`	Màu hex 3 hoặc 6 ký tự
`--gray-tint`	Số từ 0 đến 1
`--radius-base`	`sharp`, `default`, `round`, `pill`, hoặc giá trị px như `6px`

lint

npx werewolf-ui lint
npx werewolf-ui lint src --fix

Kiểm tra file .js, .jsx, .ts, .tsx, .mjs và .css, tối đa 500 file và 1 MiB mỗi file. Đường dẫn là file hoặc thư mục tính từ dự án, không dùng glob. Lint không cài gì và chạy được cả trước init. --fix chỉ áp dụng chỉnh sửa chính xác và phân tích lại trước khi ghi.

mcp

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

Khởi động MCP server local qua stdio để client gọi. Thư mục nào đã tồn tại cũng được. Xem AI agent và MCP để cài client.

tokens build

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

Cần init trước. Xuất json/dark.json và json/light.json cùng file của một nền tảng, không thay đổi seed.

Tùy chọn	Giá trị
`--platform`	`web` (mặc định), `ios` hoặc `android`
`--out`	Bắt buộc. Một thư mục bên trong dự án

docs

npx werewolf-ui docs
npx werewolf-ui docs date-picker

In URL trang của component, hoặc trang cài đặt nếu không truyền tên. Lệnh chỉ mở trình duyệt trong terminal tương tác và khi không có --json. Site mô tả phiên bản mới nhất, có thể khác bản CLI bạn đang cài.

Tùy chọn cho mọi lệnh

--help in mọi lệnh; <lệnh> --help chỉ in lệnh đó.
--yes dùng được ở mọi lệnh. Không lệnh nào hỏi lại, và --yes không bao giờ cho phép ghi đè.
--json in đúng một bản kết quả ra stdout và không gì khác: schemaVersion, command, ok, data và diagnostics.
--cwd <path> chọn app. Mỗi tùy chọn nhận một giá trị, viết --cwd ./apps/web, không viết --cwd=./apps/web.
--overwrite <path> thay một file được tạo cụ thể sau khi bạn đã xem. Đây là tùy chọn duy nhất được lặp lại.

Mã thoát

Mã	Ý nghĩa
0	Thành công. Lint không thấy lỗi, có thể còn cảnh báo.
1	Lỗi khi chạy: xung đột, ghi file hoặc cài package thất bại. Lint tìm thấy lỗi.
2	Tham số sai, component không tồn tại, seed không hợp lệ, hoặc dự án không được hỗ trợ hay chưa rõ ràng.
130	Đã hủy.

Xung đột và ghi đè

CLI ghi lại những gì nó tạo trong .werewolf/managed.json. File được tạo chưa bị sửa sẽ được cập nhật; file bạn đã sửa trả về WW_CONFLICT kèm đường dẫn chính xác, và không có gì được ghi.
--overwrite chỉ chọn được file do CLI tạo, component trong lệnh hiện tại hoặc file được xuất. Nó không bao giờ chọn được seed, werewolf.json, stylesheet của app hay AGENTS.md.
Ghi file thất bại thì được hoàn tác. Việc cài package thì không.

Mã chẩn đoán

Thông báo bằng tiếng Anh và có thể đổi; mã thì cố định. Trang Xử lý sự cố giải thích các mã hay gặp.

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.