文档 / CLI / Orca CLI 参考

orca CLI 与正在运行的 Orca 运行时通信。当 shell 脚本或 agent 需要检查工作树、启动终端、打开文件、自动化内置浏览器，或向 Orca 报告进度时，请使用它。

验证运行时¶

在设置 → 常规 → Orca CLI 中注册 CLI，然后检查它能否连接到 Orca。

GNOME Orca —— 大多数 GNOME 桌面自带的屏幕阅读器 —— 已经占用了 /usr/bin/orca，因此 Orca 的 Linux CLI 会安装为 orca-ide。不要使用 command -v orca 来检查它：在 GNOME 桌面上该命令会成功，并解析到屏幕阅读器，而不是 Orca。本页全文写作 orca —— 在 Linux 上请将其理解为 orca-ide。参见安装 → Linux。

在 macOS 和 Windows 上：

command -v orca
orca status --json

在 Linux 上：

command -v orca-ide
orca-ide status --json

如果 Orca 尚未运行：

orca open --json
orca status --json

当另一个工具需要解析结果时，请使用 --json。人类可读输出用于快速终端检查。

选择器¶

大多数命令接受选择器，而不需要长 ID：

orca repo show --repo id:<repoId> --json
orca worktree show --worktree active --json
orca worktree show --worktree path:/abs/path/to/worktree --json
orca worktree show --worktree branch:feature-name --json
orca worktree show --worktree issue:123 --json

active 和 current 会根据 shell 的当前目录或终端上下文，解析到包含当前位置的 Orca 管理工作树。在可能运行于目标工作树之外的脚本中，请使用显式选择器。对于远程运行时，请优先使用完整的服务器端选择器，例如 id:<repoId>::<absolute-worktree-path> 或 path:<absolute-server-path>，因为本地 shell 的当前目录可能不存在于运行时主机上。

选择主机¶

列出当前 Orca 主机可以访问的所有机器，以及每一台机器的选择器：

orca host list --json

结果包括本机、其已注册的 SSH 目标以及已配对的 Remote Orca Servers。对本机使用 --host local，对 SSH 目标使用 --host ssh:<target-id>，对已配对服务器使用 --environment <server-name>。SSH 行在目标连接后会包含检测到的远程平台（linux、darwin 或 win32）；较旧或已断开的目标会报告 platform unknown。它们还包含 connected，以及在已知时包含 SSH 生命周期 connectionStatus。当 SSH 标签和配对服务器名称唯一时，它们也可以解析；名称冲突时，请使用 host list 中的 ID。如果将机器名称放在错误的选择器上，Orca 会报告匹配的机器以及应使用的标志，而不是返回空结果。

运行时命令¶

orca open --json
orca status --json
orca serve --port 6768 --pairing-address 100.64.1.20 --json

orca serve 在前台启动运行时服务器，而不打开桌面窗口。将其用于 Remote Orca Servers 或无头环境，并使用 Ctrl-C 停止它。

仓库¶

orca repo list --json
orca repo add --path /abs/path/to/repo --json
orca repo show --repo id:<repoId> --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

在创建大量工作树之前设置仓库基础 ref，以便新任务默认从正确位置分支。

工作树¶

orca worktree list --repo id:<repoId> --json
orca worktree ps --json
orca worktree current --json
orca worktree show --worktree active --json
orca worktree create --repo id:<repoId> --name fix-login --json
orca worktree create --name child-task --agent codex --prompt "Investigate the flaky login test" --json
orca worktree set --worktree active --comment "reproduced failure; testing token refresh fix" --json
orca worktree rm --worktree id:<worktreeId> --force --json

当 worktree create 在 Orca 管理工作树内部运行时，如果 Orca 能够推断出关系，它会记录新工作树为子工作树。要显式指定，请传入 --parent-worktree active；如果新工作相互独立，请使用 --no-parent。

Agent 启动标志：

orca worktree create --name review-api --agent claude --setup run --json
orca worktree create --name quick-check --agent codex --prompt "Summarize the diff" --setup skip --json
orca worktree create --name hidden-setup --setup inherit --json

--agent 会在第一个终端中启动所选 agent。--prompt 会将初始工作发送给该 agent。--setup run|skip|inherit 控制仓库设置钩子；inherit 遵循仓库策略。

终端¶

orca terminal list --worktree active --json
orca terminal show --terminal <handle> --json
orca terminal read --terminal <handle> --json
orca terminal read --terminal <handle> --screen --json
orca terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json
orca terminal send --terminal <handle> --text "continue" --enter --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
orca terminal create --worktree active --title "tests" --command "npm test" --json
orca terminal split --terminal <handle> --direction horizontal --command "npm run dev" --json
orca terminal rename --terminal <handle> --title "runner" --json
orca terminal switch --terminal <handle> --json
orca terminal close --terminal <handle> --json
orca terminal close --worktree active --all --json

省略 --terminal 时，将目标设为当前工作树中的活动终端。当不确定终端正在等待什么时，请先读取再发送。

关闭会作为移除终端的一部分停止进程。对单个终端使用 --terminal <handle>，或使用 --worktree <selector> --all 以持久关闭恰好该工作区中的每个终端，包括其已保存的布局和 agent 恢复记录。如果这些终端稍后应恢复，请使用工作区 Sleep。如果执行主机无法确认每个 PTY 都已停止，批量关闭会返回失败的 unverifiable 结果，而不是声称进程已退出。 terminal stop 仅保留以兼容旧工具。

终端句柄是运行时范围的。如果 Orca 重启或某个命令报告了过期的终端句柄，请运行 orca terminal list --json 并重新获取句柄。

terminal list 会在 Orca 能够验证时报告每个终端的 executionHostId，并附带一个结果级别的 hostScope，其中包含已覆盖和已省略的主机 ID。将缺失的主机身份或范围视为不可验证，而不是本地。只有当终端的执行主机列在 hostScope.hostIds 中时，终端缺失才是其已退出的证据。

默认情况下，terminal read 返回累积的输出流，并去除终端转义序列。因此，重绘行的程序可能显示为堆叠的片段。当你需要当前渲染的帧时，请使用 --screen；响应中的 source 会标识 stream、screen 或 screen-unavailable。屏幕读取没有可分页的历史记录，因此 --screen 和 --cursor 互斥。

对于长输出，请使用游标读取。保存某次流读取中的 nextCursor，然后通过 --cursor 传回，以仅获取新输出。

文件¶

orca file open src/App.tsx --worktree active --json
orca file diff src/App.tsx --staged --worktree active --json
orca file open-changed --mode both --worktree active --json

路径相对于所选工作树。open-changed 读取 git status，并以 edit、diff 或 both 模式打开已更改的文件。

内置浏览器¶

浏览器命令控制所选工作树的 Orca 嵌入式浏览器标签页。它们不控制 Chrome、Safari 或 Orca 桌面 UI。

使用 snapshot -> act -> snapshot 循环：

orca goto --url http://localhost:3000 --worktree active --json
orca snapshot --worktree active --json
orca click --element @e3 --worktree active --json
orca fill --element @e1 --value "user@example.com" --worktree active --json
orca wait --text "Welcome" --worktree active --json
orca screenshot --worktree active --json

诸如 @e3 之类的引用来自 snapshot。在导航、标签页切换、会更改页面的点击以及任何过期引用错误之后，重新执行快照。

标签页和捕获命令：

orca tab list --worktree active --json
orca tab create --url http://localhost:3000 --worktree active --json
orca tab switch --index 1 --worktree active --json
orca capture start --worktree active --json
orca console --limit 50 --worktree active --json
orca network --limit 50 --worktree active --json
orca full-screenshot --worktree active --json
orca pdf --worktree active --json

仅对于尚无类型化 Orca 命令的浏览器操作，使用 orca exec --command "<agent-browser command>" --json。

浏览器设备模拟：

orca set device --name "iPhone 12" --worktree active --json
orca screenshot --worktree active --json

桌面计算机使用¶

对于内置浏览器之外的原生桌面应用，请使用 orca computer：

orca computer permissions --json
orca computer list-apps --json
orca computer get-app-state --app com.apple.Safari --json
orca computer click --app com.apple.Safari --element-index 12 --json
orca computer paste-text --app com.apple.Safari --text "hello" --json

有关完整工作流和权限设置，请参阅计算机使用。

移动模拟器¶

移动模拟器命令通过 Orca 的工作树范围桥接控制 iOS Simulator 设备。当代理在 Orca 内部操作时，请改用这些命令，而不是直接使用 serve-sim 或 simctl，以便生命周期和当前设备状态保持与当前工作树关联。

orca emulator list --worktree active --json
orca emulator attach "<device-name-or-udid>" --worktree active --json
orca emulator tap 0.5 0.7 --worktree active --json
orca emulator type "hello" --worktree active --json
orca emulator gesture '[{"type":"begin","x":0.5,"y":0.8},{"type":"move","x":0.5,"y":0.4},{"type":"end","x":0.5,"y":0.2}]' --worktree active --json
orca emulator button home --worktree active --json
orca emulator rotate landscape_left --worktree active --json
orca emulator exec --command "tap 0.5 0.7" --worktree active --json
orca emulator kill --worktree active --json
orca emulator shutdown --worktree active --json

坐标从 0 归一化到 1。对于单击，优先使用 tap；对于拖动或多步触摸输入，使用 gesture。当脚本必须针对特定模拟器而不是工作树的当前模拟器时，请传递 --device <udid-or-name> 或 --emulator <id>。

Linear¶

代理通过 orca-linear 技能使用 orca linear 接口（旧安装名称 linear-tickets 仍然有效）。优先使用 --json。已链接的工作树通过 --current 解析。

读取¶

orca linear issue --current --full --json
orca linear issue ENG-123 --comments --children --relations --activity --json
orca linear search "auth bug" --workspace all --json
orca linear list --filter assigned --limit 10 --json
orca linear list-issues --team ENG --state started --assignee me --json
orca linear list-issues --query auth --updated-at -P7D --cursor <cursor> --workspace <id> --json
orca linear team list --json
orca linear team states --team ENG --json
orca linear team labels --team ENG --json
orca linear project list --query launch --json

--full 会展开评论、子项、附件、关系和活动。各部分标志（--comments、--children、--attachments、--relations、--activity）可单独使用。

MCP 风格写入¶

# Create or update (omit id/--current to create; requires --team and --title on create)
orca linear save-issue --team ENG --title "Fix auth" --priority high --json
orca linear save-issue ENG-123 --state "In Progress" --assignee me --json
orca linear save-issue --current --project null --due-date null --json

orca linear relation add ENG-1 --related ENG-2 --type blocks --json
orca linear relation remove ENG-1 --related ENG-2 --type related --json

save-issue 的标签会替换完整标签集（Linear MCP save_issue 语义）。字面量 null 会清除负责人、估算、截止日期、项目或父项。

字段辅助功能（仍然有效）¶

orca linear status set --current --to "In Progress" --json
orca linear assignee set --current --me --json
orca linear priority set ENG-123 --to high --json
orca linear estimate set --current --to 3 --json
orca linear due-date set --current --to 2026-08-01 --json
orca linear label add --current --label backend --json
orca linear comment add --current --body "Investigating regression" --json
orca linear attach --current --url https://example.com/repro --title "Repro" --json
orca linear create --title "Flaky login test" --team ENG --priority high --json

运行 orca linear --help 或 orca skills get orca-linear 以获取与版本匹配的列表。当脚本可能在 Orca 关联的工作树之外运行时，请传入显式 issue id（例如 ENG-123）。

技能（本地，无需运行时）¶

列出捆绑的指南、打印与版本匹配的指南，或在无需桌面设置界面的情况下安装/更新混合技能包：

orca skills list
orca skills get orca-cli
orca skills get orchestration --references
orca skills get orchestration --reference recovery-and-cleanup
orca skills get orchestration --full
orca skills install --skill orca-cli --skill orchestration
orca skills install --all --dry-run
orca skills update --all

install / update 会调用与设置所使用的相同 npx skills 命令。它们不会连接 Orca 运行时。参见 Orca 技能。

账户（主机本地运行时）¶

在运行 Orca（orca serve 或桌面应用）的无头主机上，当远程客户端无法使用 添加账户（远程运行时作用域会禁用该按钮）时，添加受管理的 Claude/Codex 账户：

orca account list
orca account add                 # Claude by default
orca account add --agent codex

account add 会在主机上的此终端中运行 claude login / codex login，然后将捕获的凭据注册到本地运行时。Codex 使用设备授权，以便浏览器可以在另一台机器上完成。请在拥有这些账户的机器上运行这些命令——不要通过仅客户端的远程会话运行。

工件¶

通过已登录的 Orca 账户发布 HTML 或 Markdown。查看公共链接无需登录；创建/列出/更新/删除需要登录。发布默认关闭 — 必须由人工在设备上启用 设置 → 工件 → 允许发布公共工件链接。没有 CLI 标志可以授予该权限。list、unshare 和 delete 仍然可用，以便在关闭发布后审计或撤销链接。

orca artifacts share ./report.html --json
orca artifacts share ./notes.md --json
orca artifacts update ./notes.md --json
orca artifacts unshare ./notes.md --json
orca artifacts list --json
orca artifacts list --cursor <cursor> --json
orca artifacts delete <id> --json

接受的文件：.html、.htm、.md、.markdown。
share 会将编辑 token 存储在活动的 Orca 配置文件中，并且不会打印它。update / unshare 通过最初共享该文件时使用的相同本地路径和配置文件进行解析。
list 是分页的（nextCursor → --cursor）。delete 从 list 中获取工件 id，并且不需要原始文件。
相对 HTML 资源不会被上传——请共享自包含的 HTML 或绝对资源 URL。
发布/更新被拒绝时，会以 artifact_sharing_disabled 失败；请修复设置，而不是重试。
桌面端：打开本地 HTML 或 Markdown 文件并使用 共享为工件，或从侧边栏的工件页面管理链接。

自动化、环境和钩子¶

计划提示：

orca automations list --json
orca automations create --name "Daily review" --trigger daily --time 09:00 --prompt "Review open changes" --provider codex --repo id:<repoId> --disabled --json
orca automations run <automationId> --json

远程运行时环境：

orca environment add --name work-laptop --pairing-code "orca://pair?code=..." --json
orca environment list --json
orca environment rm --environment <selector> --json

代理状态钩子：

orca agent hooks status --json
orca agent hooks on --json
orca agent hooks off --json

代理习惯¶

对于自动化和代理调用，优先使用 --json。
优先使用选择器，而不是解析 UI 标签。
除非下一个输入显而易见，否则在发送输入前读取终端状态。
使用工作树注释作为进度检查点。参见工作树检查点。
对于受跟踪的多代理分派，请使用编排，而不是临时终端提示。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 orca48/orca