OriginAI CLI 命令行参考

originai CLI 是编码 Agent 与人类开发者在浏览器 Web 工作台之外获取、管理产品上下文的核心通道。在日常开发中，强烈建议优先使用 CLI——或直接调用底层映射相同 API 的 MCP 工具——而非手动编写裸 HTTP 请求。

CLI 的工程源码位于 monorepo 的 packages/skills 目录（以 originai 包名正式发布至 npm），其内置的 Agent Skill 规范正文定义于 packages/skills/src/setup.ts（SKILL_MD）。

安装与快速启动

# 免全局安装，单次直接调用：
npx originai -h
bunx originai -h   # 当本地环境具备 Bun 时强烈推荐（启动耗时 ~40ms，大幅优于 npx 的 ~1.2s）

# 或全局安装至系统环境：
npm install -g originai
# 亦可选用：bun add -g originai / pnpm add -g originai

身份认证与授权

在个人开发设备上进行日常交互开发时，仅需执行一次浏览器登录：

originai login
# 或通过：npx originai login

该命令将在默认浏览器中唤起授权页面，并在验证通过后将个人令牌安全持久化于 ~/.origin/settings.json 中——切勿将该文件提交至版本控制系统。

仅在 CI/CD 流水线或无头服务器环境中，才需要显式注入环境变量 ORIGIN_TOKEN（在 Web 控制台的 系统设置 → 访问令牌 中生成，格式通常以 oat_… 开头）。详见个人访问令牌指南。

CLI 解析访问凭据的优先级顺序如下：

1. 命令行显式传入的 --token 参数。
2. 当前进程环境变量或所在目录 .env 文件中的 ORIGIN_TOKEN。
3. 本地存储配置文件 ~/.origin/settings.json（由 originai login 写入）。

自定义服务网关端点配置

你可以将 CLI 的服务端点灵活指向本地测试栈、分支预览环境或私有网关，无需在每次命令中重复传递参数：

# 查看当前生效与持久化存储的各项端点配置：
originai config

# 将 API 请求重定向至本地 Supabase Edge Function：
originai config set api_url http://127.0.0.1:54321/functions/v1/origin-api

# 按需配置本地环境的浏览器登录页面与远程 MCP 服务端点：
originai config set web_url http://localhost:5173
originai config set mcp_url http://127.0.0.1:8787

# 清除特定的端点覆盖设置：
originai config unset api_url

本地配置文件 ~/.origin/settings.json（严禁提交至 Git）的标准结构示例如下：

{
  "token": "oat_…",
  "api_url": "http://127.0.0.1:54321/functions/v1/origin-api",
  "web_url": "http://localhost:5173",
  "mcp_url": "http://127.0.0.1:8787"
}

API 服务端点的完整解析优先级：

1. 命令行显式传入的 --api-url 参数。
2. 进程环境变量 ORIGIN_API_URL。
3. 项目根目录 .origin.json 中配置的 api_url 字段。
4. 本地配置文件 ~/.origin/settings.json 中的 api_url。
5. 官方生产环境默认生产端点。

Web 地址与 MCP 端点同样遵循上述解析范式：优先读取 ORIGIN_WEB_URL / ORIGIN_MCP_URL 环境变量，其次检索 settings.json，最后回退至生产默认值。

请注意：执行 originai logout 会安全清除本地保存的凭据令牌，但会完整保留已配置的端点覆盖设置。

关联代码仓库

# 在本地应用代码仓库的根目录下执行：
npx originai link --project <project-id>

# 关联项目的同时，部署 Agent Skill 规范及其包含的 RPML 参考文件：
npx originai link --skill
npx originai link --project <project-id> --skill

# 针对不同主流 Agent 客户端一键部署对应的指令与引导文件：
npx originai link --project <project-id> --claude-code --codex --cursor --skill

# 或一次性部署全套适配指令与规范：
npx originai link --project <project-id> --all

关联操作将在本地生成以下文件资产：

环境诊断与健康检查

npx originai doctor
npx originai whoami
npx originai install-help

doctor 命令会自动逐项核验本地登录会话、.origin.json 关联完整性、Skill 规范与指令规则文件状态，以及远程 API 的端到端网络连通性。

本地 MCP 服务（Claude Code 插件默认架构）

npx originai mcp                 # 启动标准 stdio 协议的本地 MCP 服务（自动读取本地登录凭据）
npx originai mcp config --claude # 输出适配 Claude Code 的 stdio 配置 JSON
npx originai mcp config --cursor # 输出适配 Cursor 的配置 JSON
npx originai mcp config --remote # 输出针对远程 HTTP + ORIGIN_TOKEN 模式的配置（高级/CI场景）

本地 MCP 工具与云端托管 MCP 及底层 origin-api 保持完全一致的命名规范（例如 get_diff、list_documents 等）。需要特别指出的是：MCP 工具集有意不提供直接执行 sync 的接口——在依据 Release 快照完成代码实现与校验后，请在终端显式执行 npx originai sync 推进指针。详见 MCP 与 Agent 安装参考。

完整命令参考速查表

当本地环境具备 Bun 运行时，推荐优先使用 bunx originai <command> 执行。

所有数据返回类命令默认向 stdout 输出纯净的 JSON 字符串（天然支持接入 jq 等工具流）；所有交互提示、警告及诊断状态均输出至 stderr。

规格读取的默认数据源

• 在默认情况下，所有读取命令均返回最新已发布 Release 快照中的数据——绝不会返回处于动态编辑中的工作区草稿。
• 指定 --read-type workspace 可显式读取动态的 rpml_files 工作区树。在项目发布首个 Release 之前必须使用该参数，否则默认的 Release 读取会因为尚未发布而返回 404。
• 指定 --release-tag <hash> 可精准固定读取特定的历史 Release 快照版本。

首次发布后的安全写入机制

当项目完成首次发布后，write-document 与 delete-document 操作将自动创建或追加至变更请求（返回 suggested: true）。系统无需额外的 create-change-request 接口——首次发起的暂存写入会自动完成创建。在人类成员在 OriginAI Web 控制台中**确认应用（Apply）**之前，这些写入绝不会污染工作区。

Agent 可通过 --proposal <id> 继续向特定变更请求追加修改，或指定 --new-proposal 另立请求。推荐在调用 submit-proposal 标记就绪前，先通过 describe-proposal 补充完整的修改意图与设计权衡。详见工作区与 Release 快照。

仓库同步模型与指针机制

本地配置文件 .origin.json 包含 release_hash（标识当前代码仓库最近一次完整对齐的已发布 Release 版本），以及可选的 proposal_id（实现绑定目标——当下一条 PR 旨在专项实现某份变更请求时，通过 get-proposal-diff <id> --bind 写入）。

1. 执行 get-diff：若绑定了 proposal_id，系统将返回已发布 Release 与该变更请求的差异；若未绑定，则展示本地同步指针与最新 Release 的全量差异。请始终先研读 diff。
2. 在工程代码中实现这些规格差异。
3. 若实现的是变更请求，应先在 OriginAI 中确认应用并发布新版本，随后再在本地运行 sync 推进 release_hash 指针。请注意：sync 仅在检测到新的 Release 哈希生成后，才会清除本地配置文件中的 proposal_id。

典型工作流 A —— 已有产品逆向导入（OriginAI → 本地代码库）

npx originai login
npx originai link --project <project-id> --skill
npx originai doctor
npx originai get-diff
# 编码 Agent 根据 Diff 编写实现代码
npx originai sync

典型工作流 B —— 全新产品起草（代码库 → OriginAI，首次发布前）

npx originai login
npx originai create-project --name "My App"
npx originai link --project <new-id> --skill
# 直接在命令行中以内联方式起草 RPML —— 本地无需生成物理 .rpml 文件
npx originai validate --content "<page mode='doc'>…</page>"
npx originai write-document --name "README.rpml" --content "<rpml>"
# 针对规划的每个页面路由逐一写入 .rpml，随后验证：
npx originai list-documents --read-type workspace

随后前往 OriginAI 官方 Web 界面发布首个 Release。首次发布完成后，外部 Agent 后续的所有写入将自动受控转为变更请求——遵循 list-proposals、describe-proposal、submit-proposal 的标准化协同闭环，经人类确认应用后再行发布。

避免直接编写裸 HTTP 请求调用 API

请始终优先使用官方 CLI 或 MCP 协议工具。手动编写 curl 或 fetch 调用 origin-api 极易在签名认证头、URL 编码规范或请求超时重试机制上产生偏离。若需要让 Agent 在无工具环境下通过 HTTP 自动发现 Skill 规范，参见 Agent Skills 规范。

相关内容

• Agent Skills 规范与参考
• MCP 与 Agent 安装参考
• 连接编码 Agent
• 个人访问令牌
• HTTP API 规范
• 审阅变更请求