CLI 参考手册

Planu CLI（planu）让你直接从终端管理 Planu — 安装到 AI 工具、验证 spec、运行审计等。

快速开始

# 全局安装（一次性）
npm install -g @planu/cli

# 或无需安装直接使用
planu <command>

命令

planu install

检测已安装的 AI 工具（Claude Code、Cursor、Windsurf、Zed、Cline、Continue），并将 Planu MCP 条目写入其配置文件。

planu install [--scope user|project] [--all]

Flag	说明
--scope user|project	在用户（全局）或项目级别安装。省略时会提示选择。
--all	跳过工具选择菜单，安装到所有检测到的工具。

# 交互式安装
planu install

# 以用户级别非交互地安装到所有检测到的工具
planu install --scope user --all

planu doctor

检查每个 AI 工具的所有已知配置路径，并报告 Planu MCP 条目是否存在、缺失或损坏。

planu doctor

输出示例：

Planu Doctor

  [+] Claude Code (user)    OK  ~/.claude.json
  [-] Cursor                not installed
  [?] Zed                   tool not found

Planu is installed in 1 location(s). Run `planu install` to add more.

planu uninstall

查找所有包含 Planu MCP 条目的配置文件，并在确认后将其删除。

planu uninstall [--yes]

Flag	说明
--yes / -y	跳过交互确认（适用于脚本）。

planu status

更新某个 spec 的状态（例如从 draft 变为 approved）。

planu status <specId> --set <status> [--project-id ID] [--notes "..."]

Flag	说明
--set / -s	新状态：draft、review、approved、implementing、done、blocked。
--notes / -n	与本次状态变更关联的可选审查备注。
--project-id	项目 ID。省略时从当前目录自动检测。

planu status SPEC-042 --set approved
planu status SPEC-042 --set done --notes "所有标准已验证"

planu validate

将某个 spec 与其代码库进行验证 — 检查哪些验收标准已被覆盖，并报告整体覆盖率。

planu validate <specId> [--project-id ID]

planu validate SPEC-042
planu validate SPEC-042 --project-id 1ef29aa7362bb087

planu audit

对项目运行代码质量审计，并基于 SOLID 原则、整洁代码和架构合规性给出 0–100 分的评分。

planu audit [--path .] [--project-id ID] [--spec SPEC-001]

Flag	说明
--path / -p	要审计的目录。默认为当前目录。
--spec / -s	将审计限定到特定的 spec。
--project-id	项目 ID。省略时自动检测。

planu estimate

估算某个 spec 的实现工作量 — 工时、复杂度和成本分解。

planu estimate <specId> [--project-id ID]

planu estimate SPEC-042

planu create

创建带有标题和可选元数据的新 spec。

planu create <title> [--type feature] [--description "..."] [--path .]

Flag	说明
--type / -t	Spec 类型：feature、fix、chore、spike。
--description / -d	简短描述。省略时使用标题。
--path / -p	项目目录。默认为当前目录。
--scope	Spec 的范围。
--target	目标层或模块。
--feature	父功能分组。

planu create "添加 OAuth 登录" --type feature
planu create "修复结账时的空指针" --type fix --description "购物车为空时出现空指针"

planu list

列出当前项目中的所有 spec，可按状态或类型过滤。

planu list [--status draft] [--type feature] [--project-id ID]

Flag	说明
--status / -s	按状态过滤：draft、review、approved、implementing、done、blocked。
--type / -t	按类型过滤：feature、fix、chore、spike。
--project-id	项目 ID。省略时自动检测。

planu list
planu list --status approved
planu list --type fix --status done

planu init

将某个目录初始化为 Planu 项目 — 扫描技术栈、设置语言并创建项目元数据。

planu init [path] [--locale en] [--rate 100] [--level junior|mid|senior] [--profile developer]

Flag	说明
--locale / -l	Spec 内容的语言：en、es、pt、fr、de、zh。
--rate / -r	用于成本估算的美元时薪。
--level	经验等级：junior、mid、senior。
--profile	用户画像：developer、product-owner、designer、non-technical。

planu init
planu init /path/to/project --locale zh --rate 60

planu serve

以 HTTP 传输方式而非 stdio 启动 Planu MCP 服务器。适用于远程或基于浏览器的客户端。

planu serve [--port 3100]

planu serve --port 8080

planu dashboard

打开 Planu Web 控制台 — 用于在浏览器中浏览 spec、指标和报告的本地界面。

planu dashboard [--port 5050]

planu dashboard
planu dashboard --port 9000

planu watch

监视项目目录的文件变更，并触发已配置的 hook 处理程序（on-save、on-create、on-delete）。

planu watch [path] [--hooks on-save,on-create] [--verbose] [--dry-run]

Flag	说明
--hooks / -H	逗号分隔的 hook 类型。默认：on-save,on-create,on-delete。
--verbose / -V	显示详细的 hook 执行日志。
--dry-run	预览将触发哪些 hook，而不实际执行。

planu watch
planu watch /path/to/project --hooks on-save --verbose
planu watch --dry-run

planu handoff

生成结构化的 handoff prompt，供 AI 代理自主实现某个 spec。

planu handoff <specId> [--name Agent-1] [--role implementer] [--files src/a.ts,src/b.ts]

Flag	说明
--name / -n	代理名称标签。默认：Agent-1。
--role / -r	代理角色：implementer、reviewer、tester。默认：implementer。
--files / -f	分配给该代理的逗号分隔文件列表。
--project-id	项目 ID。省略时自动检测。

planu handoff SPEC-042
planu handoff SPEC-042 --name "Backend-Agent" --role implementer --files src/api/auth.ts,src/middleware/jwt.ts

常用工作流程

在所有检测到的 Host 中安装

planu install --global

CI/CD 无头模式

在 CI 中使用相同的无限制本地命令；无需 Planu 商业授权凭据。

planu validate SPEC-042
planu audit --path /path/to/project

从终端完成完整的 SDD 周期

planu init                                  # 初始化项目
planu create "添加支付流程" --type feature
planu list --status draft                   # 查看待处理 spec
planu status SPEC-001 --set approved
planu validate SPEC-001                     # 实现后检查覆盖率
planu audit                                 # 评估代码质量

全局 Flag

这些 flag 适用于所有命令。

Flag	简写	说明
--help	-h	显示当前命令的帮助信息。
--version		显示已安装的 Planu 版本。
--json		以原始 JSON 格式输出（适用于脚本和管道）。
--quiet	-q	抑制非必要输出。
--verbose		在发生错误时显示完整的堆栈跟踪。