# 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

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

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

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

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

```bash
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](https://www.werewolf-ui.dev/vi/docs/agents.md) để cài client.

### tokens build

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

```bash
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ố](https://www.werewolf-ui.dev/vi/docs/troubleshooting.md) 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. |