CLI 参考手册

Rasen CLI（rasen）提供了用于项目初始化、校验、状态检查和管理的终端命令。这些命令与 AI 斜杠命令（如 /rasen:propose）互为补充，后者参见命令。

概览

人类命令与 Agent 命令

大多数 CLI 命令面向在终端中使用的人类。其中一部分也通过 JSON 输出支持 agent/脚本使用。

仅限人类的命令

这些命令是交互式的，面向终端使用：

兼容 Agent 的命令

这些命令支持 --json 输出，便于 AI agent 和脚本以编程方式使用：

全局选项

以下选项适用于所有命令：

初始化命令

rasen init

在你的项目中初始化 Rasen。创建文件夹结构并配置 AI 工具集成。

默认行为使用全局配置默认值：profile 为 full（所有工作流）、delivery 为 both。

rasen init [path] [options]

参数：

选项：

--profile custom 使用全局配置中当前选中的 workflows（rasen config profile）。

支持的工具 ID（--tools）： amazon-q, antigravity, auggie, bob, claude, cline, codex, forgecode, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, iflow, junie, kilocode, kimi, kiro, lingma, vibe, opencode, pi, qoder, qwen, roocode, trae, windsurf

此列表与 src/core/config.ts 中的 AI_TOOLS 对应。各工具的 skill 和命令路径参见支持的工具。

示例：

# 交互式初始化
rasen init

# 在指定目录初始化
rasen init ./my-project

# 非交互式：为 Claude 和 Cursor 配置
rasen init --tools claude,cursor

# 为所有支持的工具配置
rasen init --tools all

# 为本次运行覆盖 profile
rasen init --profile core

# 跳过提示并自动清理遗留文件
rasen init --force

创建的内容：

rasen/
├── specs/              # 你的规格（唯一事实来源）
├── changes/            # 提议的变更
└── config.yaml         # 项目配置

.claude/skills/         # Claude Code skills（选中 claude 时）
.cursor/skills/         # Cursor skills（选中 cursor 时）
.cursor/commands/       # Cursor OPSX 命令（delivery 为 both 时）
... (其他工具配置)

rasen update

升级 CLI 后更新 Rasen 指令文件。使用当前全局 profile、选中的 workflows 和 delivery 模式重新生成 AI 工具配置文件。

rasen update [path] [options]

参数：

选项：

示例：

# npm 升级后更新指令文件
npm update @atelierai/rasen
rasen update

Store（独立 Rasen 仓库）

Beta。 Store 及其上的功能（引用、工作上下文、工作集）是新特性；命令名、flag、文件格式和 JSON 输出在不同版本之间可能变化。以问题为导向的完整介绍参见 Store 指南。

Store 是你在这台机器上注册过的独立 Rasen 仓库——例如一个规划仓库或契约仓库。注册 Store 后，常规命令（list、show、status、validate、new change、archive……）可通过 --store <id> 从任意位置在其中执行。

rasen store setup

创建并注册一个本地 Store。在终端中无参数运行时，Rasen 会引导用户完成 setup。Agent 和脚本应传入显式输入并使用 --json。

rasen store setup [id] [options]

选项：

非交互式运行（--json、脚本、agent）必须同时传入 Store id 和 --path。在交互式终端中，setup 会在一个可见的、用户拥有的位置（例如 ~/rasen/<id>）通过可编辑的建议来提示位置；它绝不默认使用 Rasen 的托管数据目录。

示例：

rasen store setup
rasen store setup team-context
rasen store setup team-context --path ~/rasen/team-context --no-init-git
rasen store setup team-context --path ~/rasen/team-context --no-init-git --json

rasen store register

注册一个已存在的本地 Store 文件夹。

rasen store register [path] [options]

选项：

rasen store unregister

忘记一个本地 Store 注册，但不删除文件。

rasen store unregister <id> [--json]

当 Store 已被移动、克隆到别处，或不应再在本机的 Rasen 中显示时，使用此命令。

rasen store remove

忘记一个本地 Store 注册并删除其本地文件夹。

rasen store remove <id> [--yes] [--json]

在交互式终端中，remove 删除前会显示确切的文件夹。Agent、脚本和 JSON 调用方必须传 --yes 以确认删除。Rasen 拒绝删除不包含匹配 Store 元数据的文件夹。

rasen store list

列出本地已注册的 Store。

rasen store list [--json]
rasen store ls [--json]

rasen store doctor

检查本地 Store 的注册、元数据和 Git 存在性。

rasen store doctor [id] [--json]

doctor 仅用于诊断；它报告缺失的根、元数据不匹配和无效的本地注册表状态，但不修改 Store。

从项目引用 Store

项目仓库可以在 rasen/config.yaml 中声明其工作所依赖的 Store：

schema: spec-driven
references:
  - team-context

此后，该仓库中的 rasen instructions 输出（包括逐产物和 apply 两种界面、JSON 与人类模式）会携带每个被引用 Store 的规格索引——spec id、取自各 spec Purpose 部分的一句话摘要，以及获取命令（rasen show <spec-id> --type spec --store <id>）。该索引在每次运行时从已注册的检出实时构建；spec 内容从不被复制到输出中。

引用是只读上下文。它们绝不改变命令执行的位置：工作始终留在仓库自身的根中，向被引用的 Store 写入仍需显式的 --store 操作。无法解析的引用（例如本机未注册的 Store）会降级为索引中的一条警告并附带确切修复方法，而 instructions 仍会生成。rasen doctor 会在一处统一报告引用健康状况。

记录 Store 的克隆来源

Store 可以在其提交的身份文件中记录权威克隆源，这样上手流程绝不会卡在"注册该 Store"这一步：

rasen store setup team-context --path ~/rasen/team-context \
  --remote git@github.com:acme/team-context.git

该 remote 会落入初始提交内的 .rasen-store/store.yaml，因此每次克隆天生就知道它。对于已存在的 Store，手工编辑 store.yaml 并提交。store doctor 会显示记录的 remote（以及检出的 Git origin）；setup/register 的共享指引会点名它；register 还会把检出的 origin 记录到机器本地注册表中。

引用声明也可以携带克隆源，这样尚未拥有该 Store 的队友就能得到一条完整、可直接粘贴的修复命令（git clone <remote> <path> && rasen store register <path> --id <id>）：

references:
  - { id: team-context, remote: "git@github.com:acme/team-context.git" }

记录 remote 并不是同步：Rasen 绝不自行 clone、pull 或 push。

声明默认 Store

一个规划完全外置的仓库——没有本地 rasen/specs/ 或 rasen/changes/——可以一次性声明其 Store，而不必在每条命令上都加 --store：

# rasen/config.yaml（rasen/ 下唯一的文件）
store: team-context

此后常规命令会自动解析到所声明的 Store；根横幅和 JSON root 块会报告 source: "declared" 及 Store id，打印的提示仍会带上 --store <id>。该声明是回退机制，绝非覆盖：显式的 --store 总是优先，而含有真实规划文件夹的目录会忽略该指针（并给出警告）。要把一个指针仓库转换为本地 Rasen 根，请删除 store: 行并运行 rasen init——声明存在时 init 会拒绝搭建脚手架。

Doctor（关系健康）

一个只读问题，一处查看：Rasen 根是否健康？它引用的 Store 在本机是否可用？

rasen doctor [--store <id>] [--json]

报告将根健康状况、Store 元数据健康状况（包括记录的 remote 与检出 origin 不一致时的提示）和引用健康状况（与 instructions 所示相同的诊断，并为未解析的引用附带 clone 修复）分开呈现。任何严重程度的健康发现都以退出码 0 退出——agent 读取 status 数组；只有命令失败（无根、未知 Store）才以退出码 1 退出。doctor 绝不 clone、同步或修复。要获取组装好的集合本身而非其健康状况，请使用 rasen context。

工作上下文（组装好的集合）

本次工作通过 Rasen 声明所关联的一切，集中于一个工作集：Rasen 根及其引用的 Store。

rasen context [--store <id>] [--json] [--code-workspace <path> [--force]]

JSON 摘要可供 agent 消费（每个可用的被引用 Store 都带有其获取配方；未解析的成员带有与 instructions 和 doctor 相同的修复方法）。--code-workspace 还会写入一个包含根及可用被引用 Store（ref:<id> 文件夹）的 VS Code 工作区文件——这是本命令执行的唯一写操作，若文件已存在且未带 --force 则会拒绝。不可用的成员会被报告，绝不臆测。

"工作上下文"是组装好的集合；rasen/config.yaml 中的 context: 字段是注入到 instructions 中的项目背景——两者是不同事物。rasen doctor 回答集合是否健康；rasen context 回答集合是什么。

个人工作集

Beta。 Workset 是新 beta 界面的一部分；命令、flag 和文件格式在不同版本之间可能变化。完整介绍参见 Store 指南。

Workset 是你一起工作的那些文件夹的个人化、具名视图——一个规划根加上你选择的任何其他文件夹——保存在你的机器上，并可在你的工具中按名称重新打开。它是纯本地的：从不提交、从不共享、从不派生自声明，且删除一个 Workset 绝不触及任何成员文件夹。

rasen workset create [name] [--member <path> | --member <name>=<path>]... [--tool <id>] [--json]
rasen workset list [--json]
rasen workset open <name> [--tool <id>]
rasen workset remove <name> [--yes] [--json]

create 运行一段简短的引导流程（或通过 --member flag 非交互式接收；第一个成员是主成员——会话从这里开始）。open 启动所选工具：编辑器（VS Code、Cursor）打开一个包含所有成员的窗口并返回；CLI agent（Claude Code、codex）接管当前终端作为会话，附加所有成员且不预填提示，在你退出时结束。open 时缺失的成员文件夹会被跳过并给出提示，其余照常打开。保存的工具偏好可在每次 open 时用 --tool 覆盖。

支持一个新工具是配置而非代码。每个工具属于两种启动风格之一——workspace-file（用生成的 .code-workspace 启动）或 attach-dirs（每个成员一个 attach flag）——全局 config.json 中的 openers 键（用 rasen config edit 打开）可按字段添加工具或调整内置项：

{
  "openers": {
    "zed": { "style": "workspace-file" },
    "claude": { "attach_flag": "--dir" }
  }
}

所有 Workset 状态都位于全局数据目录的 worksets/ 文件夹下（保存的视图加上生成的 <name>.code-workspace 文件，在每次 open 时重新生成）；删除该文件夹即移除一切痕迹。

机器数据位置： 全局数据目录（worksets、Store 注册表、项目注册表、用户 schema/pipeline）和全局配置目录（config.json）在所有平台上都默认为 ~/.rasen。设置 RASEN_HOME 以同时将两者迁移到一个自定义目录；XDG_DATA_HOME/XDG_CONFIG_HOME 在 RASEN_HOME 下仍被尊重作为兼容性别名。升级后第一次运行时，位于旧平台专属位置的数据会被自动且无损地采纳到 ~/.rasen。

浏览命令

rasen list

列出你项目中的变更或规格。

rasen list [options]

选项：

示例：

# 列出所有活跃变更
rasen list

# 列出所有规格
rasen list --specs

# 供脚本使用的 JSON 输出
rasen list --json

输出（文本）：

Changes:
  add-dark-mode     No tasks      just now

rasen view

显示一个用于浏览规格和变更的交互式仪表盘。

rasen view

打开一个基于终端的界面，用于浏览你项目的规格和变更。

rasen show

显示某个变更或规格的详情。

rasen show [item-name] [options]

参数：

选项：

变更专属选项：

规格专属选项：

示例：

# 交互式选择
rasen show

# 显示特定变更
rasen show add-dark-mode

# 显示特定规格
rasen show auth --type spec

# 供解析的 JSON 输出
rasen show add-dark-mode --json

校验命令

rasen validate

校验变更和规格的结构性问题。

rasen validate [item-name] [options]

参数：

选项：

示例：

# 交互式校验
rasen validate

# 校验特定变更
rasen validate add-dark-mode

# 校验所有变更
rasen validate --changes

# 带 JSON 输出校验全部（供 CI/脚本）
rasen validate --all --json

# 严格校验并提高并行度
rasen validate --all --strict --concurrency 12

输出（文本）：

Validating add-dark-mode...
  ✓ proposal.md valid
  ✓ specs/ui/spec.md valid
  ⚠ design.md: missing "Technical Approach" section

1 warning found

输出（JSON）：

{
  "version": "1.0.0",
  "results": {
    "changes": [
      {
        "name": "add-dark-mode",
        "valid": true,
        "warnings": ["design.md: missing 'Technical Approach' section"]
      }
    ]
  },
  "summary": {
    "total": 1,
    "valid": 1,
    "invalid": 0
  }
}

生命周期命令

rasen archive

归档已完成的变更，并将增量规格合并进主规格。

rasen archive [change-name] [options]

参数：

选项：

示例：

# 交互式归档
rasen archive

# 归档特定变更
rasen archive add-dark-mode

# 无提示归档（CI/脚本）
rasen archive add-dark-mode --yes

# 归档不影响规格的工具类变更
rasen archive update-ci-config --skip-specs

执行的操作：

1. 校验该变更（除非 --no-validate）
2. 提示确认（除非 --yes）
3. 将增量规格合并进 rasen/specs/
4. 把变更文件夹移动到 rasen/changes/archive/YYYY-MM-DD-<name>/

工作流命令

这些命令支持基于产物的 OPSX 工作流。它们既适用于人类查看进度，也适用于 agent 确定下一步操作。

rasen new change

在解析到的 Rasen 根中创建变更目录和可选的、纳入版本控制的元数据。

rasen new change <name> [options]

选项：

示例：

rasen new change add-billing-api
rasen new change add-billing-api --store team-context --json

rasen status

显示某变更的产物完成状态。

rasen status [options]

选项：

示例：

# 交互式状态检查
rasen status

# 特定变更的状态
rasen status --change add-dark-mode

# 供 agent 使用的 JSON
rasen status --change add-dark-mode --json

输出（文本）：

Change: add-dark-mode
Schema: spec-driven
Progress: 2/4 artifacts complete

[x] proposal
[ ] design
[x] specs
[-] tasks (blocked by: design)

输出（JSON）：

{
  "changeName": "add-dark-mode",
  "schemaName": "spec-driven",
  "isComplete": false,
  "applyRequires": ["tasks"],
  "artifacts": [
    {"id": "proposal", "outputPath": "proposal.md", "status": "done"},
    {"id": "design", "outputPath": "design.md", "status": "ready"},
    {"id": "specs", "outputPath": "specs/**/*.md", "status": "done"},
    {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "missingDeps": ["design"]}
  ]
}

rasen instructions

获取用于创建产物或应用任务的增强指令。AI agent 用它来理解接下来要创建什么。

rasen instructions [artifact] [options]

参数：

选项：

特殊情况： 将 apply 作为 artifact 以获取任务实现指令。

示例：

# 获取下一个产物的指令
rasen instructions --change add-dark-mode

# 获取特定产物的指令
rasen instructions design --change add-dark-mode

# 获取 apply/实现指令
rasen instructions apply --change add-dark-mode

# 供 agent 消费的 JSON
rasen instructions design --change add-dark-mode --json

输出包含：

• 该产物的模板内容
• 来自 config 的项目上下文
• 来自依赖产物的内容
• 来自 config 的逐产物规则

rasen templates

显示某 schema 中所有产物解析后的模板路径。

rasen templates [options]

选项：

示例：

# 显示默认 schema 的模板路径
rasen templates

# 显示自定义 schema 的模板
rasen templates --schema my-workflow

# 供编程使用的 JSON
rasen templates --json

输出（文本）：

Schema: spec-driven

Templates:
  proposal  → ~/.rasen/schemas/spec-driven/templates/proposal.md
  specs     → ~/.rasen/schemas/spec-driven/templates/specs.md
  design    → ~/.rasen/schemas/spec-driven/templates/design.md
  tasks     → ~/.rasen/schemas/spec-driven/templates/tasks.md

rasen schemas

列出可用的工作流 schema 及其描述和产物流程。

rasen schemas [options]

选项：

示例：

rasen schemas

输出：

Available schemas:

  spec-driven (package)
    The default spec-driven development workflow
    Flow: proposal → specs → design → tasks

  my-custom (project)
    Custom workflow for this project
    Flow: research → proposal → tasks

Schema 命令

用于创建和管理自定义工作流 schema 的命令。

rasen schema init

创建一个新的项目本地 schema。

rasen schema init <name> [options]

参数：

选项：

示例：

# 交互式创建 schema
rasen schema init research-first

# 非交互式并指定产物
rasen schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

创建的内容：

rasen/schemas/<name>/
├── schema.yaml           # schema 定义
└── templates/
    ├── proposal.md       # 每个产物的模板
    ├── specs.md
    ├── design.md
    └── tasks.md

rasen schema fork

将一个已存在的 schema 复制到你的项目以供定制。

rasen schema fork <source> [name] [options]

参数：

选项：

示例：

# fork 内置的 spec-driven schema
rasen schema fork spec-driven my-workflow

rasen schema validate

校验某 schema 的结构和模板。

rasen schema validate [name] [options]

参数：

选项：

示例：

# 校验特定 schema
rasen schema validate my-workflow

# 校验所有 schema
rasen schema validate

rasen schema which

显示某 schema 解析自何处（用于调试优先级）。

rasen schema which [name] [options]

参数：

选项：

示例：

# 检查某 schema 来自何处
rasen schema which spec-driven

输出：

spec-driven resolves from: package
  Source: /usr/local/lib/node_modules/@atelierai/rasen/schemas/spec-driven

schema 优先级：

1. 项目：rasen/schemas/<name>/
2. 用户：~/.rasen/schemas/<name>/（或设置 RASEN_HOME 时为 $RASEN_HOME/schemas/<name>/）
3. 包：内置 schema

配置命令

rasen config

查看和修改全局 Rasen 配置。

rasen config <subcommand> [options]

子命令：

示例：

# 显示配置文件路径
rasen config path

# 列出所有设置
rasen config list

# 获取特定值
rasen config get telemetry.enabled

# 设置一个值
rasen config set telemetry.enabled false

# 显式设置字符串值
rasen config set user.name "My Name" --string

# 移除自定义设置
rasen config unset user.name

# 重置全部配置
rasen config reset --all --yes

# 在你的编辑器中编辑配置
rasen config edit

# 通过基于 action 的向导配置 profile
rasen config profile

# 快速预设：将 workflows 切换为 core（保留 delivery 模式）
rasen config profile core

rasen config profile 以当前状态摘要开始，随后让你选择：

• 更改 delivery + workflows
• 仅更改 delivery
• 仅更改 workflows
• 保持当前设置（退出）

若保持当前设置，不会写入任何更改，也不会显示更新提示。 若没有配置更改，但当前项目文件与你的全局 profile/delivery 不同步，Rasen 会显示警告并建议 rasen update。 按 Ctrl+C 也会干净地取消该流程（无堆栈跟踪）并以退出码 130 退出。 在工作流清单中，[x] 表示该工作流已在全局配置中选中。要将这些选择应用到项目文件，请运行 rasen update（或在项目内出现提示时选择 Apply changes to this project now?）。

交互式示例：

# 仅更新 delivery
rasen config profile
# 选择：仅更改 delivery
# 选择 delivery：仅 skills

# 仅更新 workflows
rasen config profile
# 选择：仅更改 workflows
# 在清单中切换 workflows，然后确认

工具命令

rasen feedback

提交关于 Rasen 的反馈。会创建一个 GitHub issue。

rasen feedback <message> [options]

参数：

选项：

要求： 必须安装并通过认证 GitHub CLI（gh）。

示例：

rasen feedback "Add support for custom artifact types" \
  --body "I'd like to define my own artifact types beyond the built-in ones."

rasen completion

管理 Rasen CLI 的 shell 补全。

rasen completion <subcommand> [shell]

子命令：

支持的 shell： bash, zsh, fish, powershell

示例：

# 安装补全（自动检测 shell）
rasen completion install

# 为特定 shell 安装
rasen completion install zsh

# 生成脚本以供手动安装
rasen completion generate bash > ~/.bash_completion.d/rasen

# 卸载
rasen completion uninstall

退出码

环境变量

相关文档

• 命令 - AI 斜杠命令（/rasen:propose、/rasen:apply 等）
• 工作流 - 常见模式和各命令的适用时机
• 自定义 - 创建自定义 schema 和模板
• 入门指南 - 首次设置指南