CLI 命令参考

mutsumi（TUI 启动）

启动 Mutsumi TUI 任务看板。

mutsumi [选项] [子命令]

选项	短写	说明	默认
`--path PATH`	`-p`	任务文件路径	`./mutsumi.json`（回退：`./tasks.json`）
`--watch PATH`	`-w`	额外监听的任务文件路径（可重复）	—
`--version`		显示版本号并退出	—
`--help`		显示帮助并退出	—

示例

# 启动 TUI（监听当前目录的 mutsumi.json）
mutsumi

# 指定文件路径
mutsumi --path /path/to/mutsumi.json

# 同时监听多个文件（多项目）
mutsumi --path ~/proj-a/mutsumi.json -w ~/proj-b/mutsumi.json

# 打印版本号
mutsumi --version

首次启动时，引导向导会自动运行。详见启动流程。

mutsumi add

创建新任务并追加到 mutsumi.json。

mutsumi add 标题 [选项]

选项	短写	类型	可选值	默认
`--priority`	`-P`	选择	`high`, `normal`, `low`	`normal`
`--scope`	`-s`	选择	`day`, `week`, `month`, `inbox`	配置中的 `default_scope`
`--tags`	`-t`	字符串	逗号分隔	`[]`
`--description`	`-d`	字符串	自由文本	—

示例

# 最简
mutsumi add "修复登录 Bug"

# 完整选项
mutsumi add "修复登录 Bug" -P high -s day -t "bugfix,urgent" -d "刷新时会话过期"

# 短标志
mutsumi add "写测试" -P low -s week -t "dev"

自动生成唯一 ID 和 created_at 时间戳。

mutsumi list

列出 mutsumi.json 中的任务。

mutsumi list [选项]

选项	短写	类型	可选值	默认
`--scope`	`-s`	选择	`day`, `week`, `month`, `inbox`	全部
`--done / --no-done`		标志		显示全部

示例

# 列出所有任务
mutsumi list

# 按 scope 过滤
mutsumi list --scope day

# 仅显示待办
mutsumi list --no-done

# 仅显示已完成
mutsumi list --done

mutsumi done

标记任务完成（支持 ID 前缀匹配）。

mutsumi done TASK_ID

参数	说明
`TASK_ID`	完整任务 ID 或唯一前缀

示例

# 完整 ID
mutsumi done 01JQ8X7K3M0000000000000001

# 前缀匹配
mutsumi done 01JQ

# 前缀不唯一时，列出匹配项
mutsumi done 01
# 错误：多个任务匹配 '01'，请输入更长的前缀。

设置 status 为 "done" 并自动填充 completed_at。

mutsumi edit

编辑任务字段（支持 ID 前缀匹配）。

mutsumi edit TASK_ID [选项]

选项	短写	类型	可选值	说明
`--title`		字符串		新标题
`--priority`	`-P`	选择	`high`, `normal`, `low`	新优先级
`--scope`	`-s`	选择	`day`, `week`, `month`, `inbox`	新 scope
`--tags`	`-t`	字符串	逗号分隔	替换标签
`--description`	`-d`	字符串	自由文本	新描述

示例

# 改标题
mutsumi edit 01JQ --title "新标题"

# 改优先级和 scope
mutsumi edit 01JQ -P low -s week

# 替换标签
mutsumi edit 01JQ -t "docs,review"

# 更新描述
mutsumi edit 01JQ -d "需求变更"

mutsumi rm

删除任务（支持 ID 前缀匹配）。

mutsumi rm TASK_ID

参数	说明
`TASK_ID`	完整任务 ID 或唯一前缀

示例

mutsumi rm 01JQ

删除任务及其所有子任务。

mutsumi init

生成模板 mutsumi.json。

mutsumi init [选项]

选项	说明
`--force`	覆盖已有文件
`--personal`	初始化个人任务文件 `~/.mutsumi/mutsumi.json`
`--project`	在当前目录创建 `mutsumi.json` 并注册为项目源

示例

# 在当前目录创建 mutsumi.json
mutsumi init

# 覆盖已有文件
mutsumi init --force

# 初始化个人任务
mutsumi init --personal

# 创建并注册为项目
mutsumi init --project

mutsumi setup

配置 AI Agent 集成。将 Agent Skills 通过符号链接安装到 Agent 的技能目录。

mutsumi setup [选项]

选项	短写	类型	可选值	默认
`--agent`	`-a`	选择	`claude-code`, `codex-cli`, `opencode`, `gemini-cli`, `aider`, `custom`	—
`--mode`		选择	`skills`, `skills+project-doc`, `snippet`	`skills`

模式说明

模式	行为
`skills`	将 5 个 Mutsumi 技能文件（`mutsumi-manage`、`mutsumi-track`、`mutsumi-plan`、`mutsumi-report`、`mutsumi-context`）以符号链接形式从 `~/.mutsumi/skills/` 安装到 Agent 的技能目录。
`skills+project-doc`	安装技能，并将 `## Mutsumi Task Integration` 部分追加到 Agent 的项目文档（`CLAUDE.md`、`AGENTS.md` 等）。
`snippet`	将集成 prompt 打印到标准输出，供手动粘贴。不安装任何文件。

安装的技能

技能	用途	自动触发？
`mutsumi-manage`	任务增删改查（添加、编辑、完成、删除）	否 — 用户请求时
`mutsumi-track`	工作时自动更新任务进度	是
`mutsumi-plan`	将目标分解为子任务	否 — 用户请求时
`mutsumi-report`	生成状态摘要	否 — 用户请求时
`mutsumi-context`	会话开始时加载任务板上下文	是

技能目录

Agent	目录
Claude Code	`~/.claude/skills/`
Codex CLI	`~/.agents/skills/`
Gemini CLI	`~/.gemini/skills/`
OpenCode	`~/.config/opencode/skills/`

示例

# 列出可用 Agent 和模式
mutsumi setup

# 为 Claude Code 安装技能（默认模式）
mutsumi setup --agent claude-code

# 安装技能 + 注入项目文档到 CLAUDE.md
mutsumi setup --agent claude-code --mode skills+project-doc

# 打印 prompt 供手动使用（Aider、自定义 Agent）
mutsumi setup --agent custom --mode snippet

# 为其他 Agent 安装技能
mutsumi setup --agent gemini-cli
mutsumi setup --agent codex-cli
mutsumi setup --agent opencode

重复运行是安全的 —— 会替换过期的符号链接，不会重复安装。

mutsumi migrate

从旧版文件名和配置位置迁移。

mutsumi migrate [选项]

选项	说明
（无）	在当前目录将 `tasks.json` 重命名为 `mutsumi.json`
`--config`	迁移配置目录（`~/.config/mutsumi/` → `~/.mutsumi/`）
`--all`	同时迁移任务文件和配置目录

示例

# 迁移 tasks.json → mutsumi.json
mutsumi migrate

# 迁移配置目录
mutsumi migrate --config

# 全部迁移
mutsumi migrate --all

mutsumi project

管理注册的项目源。

mutsumi project add

mutsumi project add PATH

注册一个项目目录为数据源。该目录应包含（或将包含）mutsumi.json。

mutsumi project add .
mutsumi project add ~/projects/saas-app

mutsumi project remove

mutsumi project remove NAME

取消注册一个项目。

mutsumi project remove saas-app

mutsumi project list

mutsumi project list

列出所有注册的项目及其路径。

mutsumi validate

校验任务文件的 schema。

mutsumi validate

校验 mutsumi.json（或 --path 指定的文件）。报告缺失必填字段、无效枚举值和格式错误。

示例

# 校验默认文件
mutsumi validate

# 校验指定文件
mutsumi -p /path/to/mutsumi.json validate

mutsumi schema

输出 mutsumi.json 的 JSON Schema。

mutsumi schema

示例

# 打印到终端
mutsumi schema

# 输出到文件
mutsumi schema > schema.json

ID 前缀匹配

接受 TASK_ID 参数的命令（done、edit、rm）支持前缀匹配。无需输入完整 ID：

mutsumi done 01EX    # 如果只有一个 ID 以 "01EX" 开头则匹配

前缀不唯一时，Mutsumi 会列出所有匹配项并要求你输入更长的前缀。

退出码

代码	含义
`0`	成功
`1`	一般错误（文件未找到、ID 不唯一等）
`2`	参数无效