orca-cli

Orca CLI

🧭 调度后端 — 选择成本更低的 Agent／模型、并行运行多个 worker、opencode／编排语法 → 查看 orca-dispatch-reference（唯一事实来源，请勿在此重复语法）。

当 Orca 正在运行的编辑器／运行时是事实来源时，请使用 orca。在 Linux 上，凡是此文件中写到 orca 的地方，都请使用 orca-ide。

如果 Orca 状态无关紧要，请使用普通 Shell 工具。

从这里开始

command -v orca || command -v orca-ide
orca status --json
orca worktree ps --json
orca terminal list --json

如果 Orca 未运行，请启动它：

orca open --json
orca status --json

对于由 Agent 驱动的调用，优先使用 --json。如果缺少 CLI，请明确说明，而不是先检查源文件。

工作树

Orca 工作树／工作区是 Orca 对某个仓库检出及其元数据、终端、浏览器标签页和 UI 状态的跟踪视图。

常用命令：

orca repo list --json
orca repo show --repo id:<repoId> --json
orca repo add --path /abs/repo --json
orca repo set-base-ref --repo id:<repoId> --ref origin/main --json
orca repo search-refs --repo id:<repoId> --query main --limit 10 --json
orca worktree list --repo id:<repoId> --json
orca worktree ps --json
orca worktree current --json
orca worktree show --worktree <selector> --json
orca worktree create --repo id:<repoId> --name related-task --json
orca worktree create --name child-task --agent codex --prompt "hi" --json
orca worktree create --name independent-task --no-parent --json
orca worktree set --worktree id:<worktreeId> --display-name "My Task" --json
orca worktree set --worktree active --comment "reproduced bug; testing fix" --json
orca worktree rm --worktree id:<worktreeId> --force --json

选择器：

• id:<worktreeId>、path:<absolutePath>、branch:<branchName>、issue:<number>
• active／current 表示从 Shell 当前工作目录所在位置，获取外围由 Orca 管理的工作树

谱系规则：

• 在由 Orca 管理的工作树内创建时，只要条件允许，Orca 会推断当前工作区为父级。
• 如果需要明确指定子级关系，请使用 --parent-worktree active。
• 只有在新工作独立时，才使用 --no-parent。
• 如果省略 --repo，只要条件允许，Orca 会从当前 Orca 工作树推断仓库。

Agent／设置标志：

orca worktree create --name task --agent codex --prompt "hi" --json
orca worktree create --name task --agent claude --setup run --json
orca worktree create --name task --setup skip --json
orca worktree create --name task --run-hooks --json

• --agent <id> 会在第一个终端中启动该 Agent；--prompt <text> 会向其发送初始任务。
• --setup run|skip|inherit 控制仓库设置钩子。默认值为 inherit，会遵循仓库的设置策略。
• --run-hooks 是 --setup run 的旧版别名；它还会显示／激活新工作树。
• --agent、--activate 和 --run-hooks 都会显示新工作树。普通创建会让工作树留在后台。
• 让 Orca 根据仓库设置选择设置终端的位置，包括标签页还是分屏。不要手动创建额外的设置终端。
• 如果较旧的已安装 CLI 不接受 --agent、--prompt 或 --setup，请先正常创建工作树，然后运行 orca terminal create --worktree <selector> --command "codex"；如果需要提示词，再运行 orca terminal send。

工作树评论

工作树评论是在 Orca 工作区列表／卡片中显示的简短状态文本，用于快速了解进度。

编码 Agent 应在有意义的检查点更新当前工作树评论：

orca worktree set --worktree active --comment "fix implemented; running integration tests" --json

在复现问题、修复、验证、移交或遇到阻碍等有意义的状态变化后更新。评论应简短且保持最新；除非请求了 Orca 状态，否则更新失败时尽力而为即可。

终端

常用命令：

orca terminal list --worktree id:<worktreeId> --json
orca terminal show --terminal <handle> --json
orca terminal read --terminal <handle> --json
orca terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json
orca terminal read --json
orca terminal send --terminal <handle> --text "continue" --enter --json
orca terminal send --text "echo hello" --enter --json
orca terminal wait --terminal <handle> --for exit --timeout-ms 5000 --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
orca terminal stop --worktree id:<worktreeId> --json
orca terminal create --json
orca terminal create --title "Worker" --json
orca terminal create --worktree active --command "codex" --json
orca terminal split --terminal <handle> --direction vertical --json
orca terminal split --terminal <handle> --direction horizontal --command "npm test" --json
orca terminal rename --terminal <handle> --title "New Name" --json
orca terminal switch --terminal <handle> --json
orca terminal close --terminal <handle> --json

终端规则：

• 大多数命令都可以省略 --terminal；省略时表示当前工作树中的活动终端。
• 除非接下来的输入显而易见，否则请先使用 terminal read，再使用 terminal send。
• 仅在直接输入终端内容，或发送无需任务状态、收件箱或回复跟踪的一次性提示词时，使用 terminal send。
• 对于结构化协作，请调用 orchestration 技能；它会使用 orca orchestration ... 命令处理消息、移交、任务 DAG、调度、收件箱／回复流程和协调器循环。
• 对于 Claude Code、Gemini 和 Codex 等 Agent CLI，请使用 terminal wait --for tui-idle；务必传入 --timeout-ms。
• 终端句柄的作用域限于运行时。如果 Orca 重启或返回 terminal_handle_stale，请使用 terminal list 重新获取。
• 对于较长的输出，请使用游标读取。显示受限的尾部预览后，从 oldestCursor 开始翻页；游标读取后，当 limited 为 true 且 nextCursor !== latestCursor 时，继续使用 nextCursor。
• --direction horizontal 会左右分屏。--direction vertical 会上下分屏。

自动化

自动化是由所选提供方定时运行的 Orca 提示词，可针对由仓库创建的工作树或现有工作区运行。

orca automations list --json
orca automations show <automationId> --json
orca automations create --name "Daily review" --trigger daily --time 09:00 --prompt "Review open changes" --provider codex --repo id:<repoId> --json
orca automations create --name "Weekday triage" --trigger "0 9 * * 1-5" --prompt "Triage issues" --provider claude --repo path:/abs/repo --disabled --json
orca automations create --name "Inbox digest" --trigger hourly --prompt "Summarize unread mail" --provider codex --workspace active --reuse-session --json
orca automations edit <automationId> --trigger weekdays --time 09:30 --fresh-session --json
orca automations run <automationId> --json
orca automations runs --id <automationId> --json
orca automations remove <automationId> --json

计划接受 hourly、daily、weekdays、weekly、5 字段 cron 或 RRULE。对 daily/weekdays/weekly 使用 --time <HH:MM>，仅对 weekly 使用 --day <0-6>，其中星期日为 0。

使用 --repo <selector> 为每次运行创建新的工作树，或使用 --workspace <selector> / --workspace-mode existing 指定现有 Orca 工作树。--repo 和 --workspace 不能同时使用。仅对现有工作区自动化使用 --reuse-session；如果之前的终端已不存在，Orca 会回退到新会话。测试设置时，建议使用 --disabled。

内置浏览器

内置浏览器是 Orca 嵌入式浏览器标签页界面，仅限 Orca 工作树使用；它不是 Chrome/Safari，也不是桌面应用界面。

这些命令仅控制 Orca 嵌入式浏览器标签页。对于外部 Chrome/Safari/网页视图或 Orca 应用外壳/设置，请使用 Computer Use 技能/工具。如果用户明确要求通过 Orca CLI 控制桌面，请使用 orca computer ...；不要使用浏览器命令控制桌面界面。

使用“快照-交互-重新快照”循环：

orca goto --url https://example.com --json
orca snapshot --json
orca click --element @e3 --json
orca snapshot --json

常用命令：

orca goto --url <url> --json
orca back --json
orca reload --json
orca snapshot --json
orca screenshot --json
orca full-screenshot --json
orca pdf --json
orca click --element <ref> --json
orca fill --element <ref> --value <text> --json
orca type --input <text> --json
orca select --element <ref> --value <value> --json
orca check --element <ref> --json
orca scroll --direction down --amount 1000 --json
orca hover --element <ref> --json
orca focus --element <ref> --json
orca keypress --key Enter --json
orca upload --element <ref> --files <paths> --json
orca wait --text <text> --json
orca wait --url <substring> --json
orca wait --selector <css> --json
orca wait --load networkidle --json
orca eval --expression <js> --json
orca tab list --json
orca tab create --url <url> --json
orca tab switch --index <n> --json
orca tab close --index <n> --json
orca cookie get --json
orca capture start --json
orca console --limit 50 --json
orca network --limit 50 --json
orca exec --command "help" --json

浏览器规则：

• 导航、切换标签页、点击导致页面变化后，以及出现任何 browser_stale_ref 后，都要重新获取快照。
• 类似 @e1 的引用由 snapshot 分配，作用范围限于单个标签页，并会在导航或切换标签页后失效。
• 浏览器命令默认针对当前工作树及其活动标签页。仅在确有需要时使用 --worktree all。
• 并发执行浏览器操作时，运行 orca tab list --json，读取 tabs[].browserPageId，并在后续命令中传入 --page <browserPageId>。
• 使用类型化的标签页命令（orca tab list/create/close/switch），不要使用 orca exec --command "tab ..."，这样 Orca 才能保持 UI 状态同步。
• 页面异步变化后，优先使用 wait --text、--url、--selector 或 --load，而不是直接等待一段时间。
• 不常用的工作流可以使用上述类型化命令，或通过 orca exec --command "<agent-browser command>" 透传命令。
• 如果 fill 或 type 在自定义输入框上失败，请尝试 orca focus --element @e1 --json，然后运行 orca inserttext --text "text" --json。

常见问题恢复方法：

• browser_no_tab：使用 orca tab create --url <url> --json 打开标签页。
• browser_stale_ref：运行 orca snapshot --json，并使用最新引用重试。
• browser_tab_not_found：切换或关闭标签页前，运行 orca tab list --json。

下一步操作

确认 orca status --json，除非本轮已经检查过；然后选择最适合当前任务的命令：worktree ps/current/create、terminal list/read/wait/send、automations list 或内置浏览器 snapshot。