CLI 概览

概览在终端执行的 moai(Go 二进制)的所有命令与标志。它与在 Claude Code 对话窗输入的 /moai(斜杠子命令)是完全不同的工具 —— 本页只讲终端 CLI。

各命令的详细参考(标志、子命令、示例)请见 CLI 参考 部分。

moai --help

moai CLI 分为三组。

用 moai version 确认当前安装的版本。

moai version

╭────────────────────────╮
│                        │
│    moai-adk v3.0.0     │
│                        │
│                        │
╰────────────────────────╯
 v3.0.0   none   built unknown

框式横幅下方一行按 <版本> <提交哈希> built <构建时刻> 顺序显示。若像 go install 那样在无 ldflags 下构建,提交显示为 none,构建时刻显示为 unknown。

初始化项目。交互式向导会设置语言、Git 自动化、模型策略、harness 配置文件等。

moai init [project-name] [OPTIONS]

# 初始化新项目(交互式向导)
moai init my-project

# 安装到既有文件夹
cd my-existing-project
moai init

# 非交互(CI/CD)
moai init --non-interactive

详细的向导步骤请参阅初始设置页面。

将 MoAI-ADK 更新到最新版本。不带标志运行时会一并更新二进制与模板,用户自定义资产会自动保留。

moai update [OPTIONS]

# 默认更新(二进制 + 模板)
moai update

# 仅确认是否有新版本
moai update --check

# 重新运行设置向导
moai update -c

# 仅同步模板
moai update --templates-only

详细的更新流程请参阅更新页面。

执行系统诊断。检查 Git、项目结构、配置文件、各语言的开发工具。

moai doctor [OPTIONS]

# 完整诊断
moai doctor

# 详细诊断
moai doctor --verbose

# 导出诊断结果
moai doctor --export diagnostics.json

一目了然地查询项目状态。显示是否已初始化、SPEC 数量、配置文件数。

moai status

这是无标志的只读命令。详细的输出内容请参阅项目状态页面。

综合查询活跃会话、工作树、harness 的只读命令。

moai inventory [OPTIONS]

详细的 JSON schema 与使用示例请参阅moai inventory页面。

管理 Claude Code 设置配置文件。可为每个配置文件维护独立的模型、语言、显示设置。

moai profile [COMMAND]

用 -p 标志指定运行时的配置文件:

moai cc -p work       # 用 work 配置文件运行 Claude
moai glm -p cost-save # 用 cost-save 配置文件运行 GLM

详情请参阅配置文件管理页面。

处理 Claude Code 钩子事件的调度器。由 settings.json 的钩子设置以 moai hook <event> 形式调用。

moai hook <event>

moai hook 调度器把标准 Claude Code 钩子事件与 MoAI 专用内部动作合在一起,共提供 42 个子命令。所有名称均为 kebab-case。下面是有代表性的事件。

钩子事件数与子命令数是两个不同的数字。 moai doctor hook 显示的 30 是 Claude Code 定义的钩子事件种类,这里的 42 是 moai hook 接受的子命令数量。由于 MoAI 专用内部动作没有对应事件也作为子命令存在,两者并不一致。

还包含 MoAI 专用子命令。

钩子不由用户直接执行 —— Claude Code 的 settings.json 会自动调用。

管理 Git worktree 以进行并行 SPEC 开发。

moai worktree <COMMAND> [ARGS]...

进入工作树是启动器的职责。列表查询则直接用 git。

moai cc -w feat-login           # 在工作树中开始工作 (不存在则创建)
moai cc -w feat-login --spawn   # 保留当前会话,在新 tmux 窗口中打开
git worktree list               # 工作树列表

moai cc 和 moai glm 使用明确选择的后端启动 Claude Code。旧 CG 配置必须先迁移才能启动。

moai cc [-p profile] [-- claude-args...]
moai glm [-p profile] [-- claude-args...]

moai cg 已停用。它会显示迁移提示并退出，不会启动 Claude 或 GLM，也不是 moai cc 的别名。项目中若仍有 llm.team_mode: cg，必须先明确选择迁移方案，才能启动会话。 CG 停用与配置迁移

三条启动命令共同支持的标志。

moai cc 额外支持以下标志。

auto 权限模式在 GLM(第三方提供者)中不可用 —— 仅在 moai cc 中支持。

moai cc 按下面的顺序查找会话模型,并把找到的第一个值作为 --model 传给 Claude Code。

1. 显式指定的 --model 参数
2. 配置文件中的模型(在 moai profile setup 里选的值)
3. 环境变量 ANTHROPIC_MODEL(仅本次启动)
4. 项目 .claude/settings.local.json 里的 model(仅本项目)
5. 该配置文件的用户级 settings.json 中用 /model 保存的值 —— 启动时会用一行提示,例如 model: opus (user /model)
6. 以上都为空时不传任何值。此时由项目 .claude/settings.json 里的 model 固定值决定会话模型,启动器会指出该值以及修改方法

越具体、越新近由用户直接指定的,优先级越高。第 3 步和第 4 步由 Claude Code 自己应用,所以启动器不传 --model,直接让路。项目设置优先于用户级设置,所以没有第 5 步时,用 /model 选的模型会被项目固定值盖住。moai glm 不适用这条规则:GLM 需要以槽位别名传入模型,而在 Anthropic 账户里用 /model 选的值属于另一个模型系列,会连到错误的槽位。

为当前会话注册·查询·解除基于条件的自主 goal 循环。在条件满足之前,每个回合结束时进行评估。

moai goal <COMMAND>

管理用于跨越 /clear 边界续接会话的 auto-resume 交接待处理记录。

moai handoff <COMMAND>

管理用于缓解多会话竞态的活跃会话协调注册表。

moai session <COMMAND>

启动基于浏览器的配置编辑器 MoAI Web Console。

moai web [OPTIONS]

显示版本、commit 哈希、构建日期。

moai version
moai --version    # 相同

按智能体逐一分配模型的旧性能层级系统已经退役。v3.2 起，子代理沿用主会话的模型与推理深度 —— 生成子代理时不传 model 也不传 effort，MoAI 智能体定义对两者都不作声明。模型策略的位置上剩下的，是会话层面的一个选择：moai profile setup 的会话模型策略问题，决定以此配置文件启动的 Claude 会话的默认推理强度（未单独选择推理强度时的回退值）。

# 配置会话模型策略（以及配置文件的其余全部）
moai profile setup

# 已退役的逐智能体旗标只打印弃用警告，没有任何效果
moai init my-project --model-policy high

旧的 --model-policy、--profile、--high、--medium-alias、--low 旗标是已弃用的桩：为脚本兼容仍接受值，但没有任何效果，并打印指向 moai profile setup 的警告。会话级模型·effort 调节见模型策略页面，矩阵的退役见配置矩阵页面。

• 快速开始
• 安装
• 更新
• 初始设置
• 配置文件管理
• 项目状态