orca-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Orca CLI

Use this skill when the task should go through Orca's control plane rather than directly through

git

, shell PTYs, or ad hoc filesystem access.

当任务需要通过Orca的控制平面而非直接通过

git

、shell PTY或临时文件系统访问时，请使用此技能。

When To Use

使用场景

Use

orca

for:

worktree orchestration inside a running Orca app
updating the current worktree comment with meaningful progress checkpoints
reading Orca-managed terminals and sending input to non-agent terminals
stopping or waiting on Orca-managed terminals
accessing repos known to Orca Do not use
```
orca
```
when plain shell tools are simpler and Orca state does not matter.

Examples:

creating one Orca worktree per GitHub issue
updating the current worktree comment after a significant checkpoint, such as reproducing a bug, validating a fix, or handing off for review
finding the Claude Code terminal for a worktree and reading its status
checking which Orca worktrees have live terminal activity

在以下场景使用

orca

：

在运行中的Orca应用内编排工作树
更新当前工作树注释，记录重要的进度检查点
读取Orca管理的终端并向非代理终端发送输入
停止或等待Orca管理的终端
访问Orca已知的仓库当普通shell工具更简单且不涉及Orca状态时，请勿使用
```
orca
```
。

示例：

为每个GitHub Issue创建一个Orca工作树
在完成重要检查点后更新当前工作树注释，例如复现bug、验证修复或提交审核
查找工作树对应的Claude Code终端并读取其状态
检查哪些Orca工作树有活跃的终端活动

Preconditions

前置条件

Prefer the public
```
orca
```
command first
Orca editor/runtime should already be running, or the agent should start it with
```
orca open
```
Do not begin by inspecting Orca source files just to decide how to invoke the CLI. The first step is to check whether the installed
```
orca
```
command exists.
Do not assume a generic shell environment variable proves the agent is "inside Orca". For normal agent flows, the public CLI is the supported surface, but avoid wasting a round trip on probe-only checks when a direct Orca action would answer the question.

First verify the public CLI is installed:

bash

command -v orca

Then use the public command:

bash

orca status --json

If the task is about Orca worktrees or Orca terminals, do this before any codebase exploration:

bash

command -v orca
orca status --json

If the agent truly needs to confirm that the current directory is inside an Orca-managed worktree, use:

bash

orca worktree current --json

orca

is not on PATH, say so explicitly and stop or ask the user to install/register the CLI before continuing.

优先使用公开的
```
orca
```
命令
Orca编辑器/运行时应已启动，或代理应通过
```
orca open
```
启动它
不要为了决定如何调用CLI而先检查Orca源代码文件。第一步应检查已安装的
```
orca
```
命令是否存在。
不要假设通用shell环境变量能证明代理处于“Orca内部”。对于常规代理流程，公开CLI是受支持的操作界面，但当直接执行Orca操作即可解决问题时，避免浪费一次往返仅做探测性检查。

首先验证公开CLI是否已安装：

bash

command -v orca

然后使用公开命令：

bash

orca status --json

如果任务涉及Orca工作树或Orca终端，请在探索代码库前执行以下操作：

bash

command -v orca
orca status --json

如果代理确实需要确认当前目录是否在Orca管理的工作树内，请使用：

bash

orca worktree current --json

如果

orca

不在PATH中，请明确告知用户并停止操作，或要求用户先安装/注册CLI再继续。

Core Workflow

核心工作流

Confirm Orca runtime availability:

bash

orca status --json

If Orca is not running yet:

bash

orca open --json
orca status --json

Discover current Orca state:

bash

orca worktree ps --json
orca terminal list --json

Resolve a target worktree or terminal handle.
Act through Orca:

```
worktree create/set/rm
```
```
terminal read/send/wait/stop
```

When the agent reaches a significant checkpoint in the current worktree, update the Orca worktree comment so the UI reflects the latest work-in-progress:

bash

orca worktree set --worktree active --comment "reproduced auth failure with aws sts; testing credential-chain fix" --json

Why: the worktree comment is Orca's lightweight, agent-writable status field. Keeping it current gives the user an at-a-glance summary of what the agent most recently proved, changed, or is waiting on.

确认Orca运行时可用：

bash

orca status --json

如果Orca尚未运行：

bash

orca open --json
orca status --json

发现当前Orca状态：

bash

orca worktree ps --json
orca terminal list --json

解析目标工作树或终端句柄。
通过Orca执行操作：

```
worktree create/set/rm
```
```
terminal read/send/wait/stop
```

当代理在当前工作树中到达重要检查点时，更新Orca工作树注释，使UI反映最新的工作进展：

bash

orca worktree set --worktree active --comment "reproduced auth failure with aws sts; testing credential-chain fix" --json

原因：工作树注释是Orca的轻量级、代理可写入的状态字段。保持其更新能让用户快速了解代理最近验证、修改的内容，或正在等待的事项。

Command Surface

命令界面

Repo

仓库

bash

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

bash

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

Worktree

工作树

bash

orca worktree list --repo id:<repoId> --json
orca worktree ps --json
orca worktree current --json
orca worktree show --worktree id:<worktreeId> --json
orca worktree create --repo id:<repoId> --name my-task --issue 123 --comment "seed" --json
orca worktree set --worktree id:<worktreeId> --display-name "My Task" --json
orca worktree set --worktree active --comment "reproduced bug; collecting logs from staging" --json
orca worktree set --worktree active --comment "waiting on review" --json
orca worktree rm --worktree id:<worktreeId> --force --json

Worktree selectors supported in focused v1:

```
id:<worktree-id>
```
```
path:<absolute-path>
```
```
branch:<branch-name>
```
```
issue:<number>
```
```
active
```
/
```
current
```
to resolve the enclosing Orca-managed worktree from the shell
```
cwd
```

bash

orca worktree list --repo id:<repoId> --json
orca worktree ps --json
orca worktree current --json
orca worktree show --worktree id:<worktreeId> --json
orca worktree create --repo id:<repoId> --name my-task --issue 123 --comment "seed" --json
orca worktree set --worktree id:<worktreeId> --display-name "My Task" --json
orca worktree set --worktree active --comment "reproduced bug; collecting logs from staging" --json
orca worktree set --worktree active --comment "waiting on review" --json
orca worktree rm --worktree id:<worktreeId> --force --json

聚焦版v1支持的工作树选择器：

```
id:<worktree-id>
```
```
path:<absolute-path>
```
```
branch:<branch-name>
```
```
issue:<number>
```
```
active
```
/
```
current
```
通过shell的
```
cwd
```
解析当前Orca管理的工作树

Terminal

终端

Use selectors to discover terminals, then use the returned handle for repeated live interaction.

bash

orca terminal list --worktree id:<worktreeId> --json
orca terminal show --terminal <handle> --json
orca terminal read --terminal <handle> --json
orca terminal send --terminal <handle> --text "continue" --enter --json
orca terminal wait --terminal <handle> --for exit --timeout-ms 5000 --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 30000 --json
orca terminal stop --worktree id:<worktreeId> --json
orca terminal create --json
orca terminal create --title "My Terminal" --json
orca terminal create --worktree path:/projects/myapp --command "npm test" --json
orca terminal split --terminal <handle> --direction vertical --json
orca terminal split --terminal <handle> --direction horizontal --command "npm run dev" --json
orca terminal rename --terminal <handle> --title "New Name" --json
orca terminal switch --terminal <handle> --json
orca terminal close --terminal <handle> --json
orca terminal send --text "echo hello" --enter --json
orca terminal read --json

Why:

--terminal

is optional for most commands. When omitted, Orca auto-resolves to the active terminal in the current worktree (same as browser commands target the active tab). Use explicit

--terminal <handle>

when operating on a specific pane.

Why: terminal handles are runtime-scoped and may go stale after reloads. If Orca returns

terminal_handle_stale

, reacquire a fresh handle with

terminal list

Why:

--direction horizontal

splits the pane left and right (new pane appears to the right).

--direction vertical

splits the pane top and bottom (new pane appears below). This matches VS Code's split convention. Default is horizontal.

使用选择器发现终端，然后使用返回的句柄进行重复的实时交互。

bash

orca terminal list --worktree id:<worktreeId> --json
orca terminal show --terminal <handle> --json
orca terminal read --terminal <handle> --json
orca terminal send --terminal <handle> --text "continue" --enter --json
orca terminal wait --terminal <handle> --for exit --timeout-ms 5000 --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 30000 --json
orca terminal stop --worktree id:<worktreeId> --json
orca terminal create --json
orca terminal create --title "My Terminal" --json
orca terminal create --worktree path:/projects/myapp --command "npm test" --json
orca terminal split --terminal <handle> --direction vertical --json
orca terminal split --terminal <handle> --direction horizontal --command "npm run dev" --json
orca terminal rename --terminal <handle> --title "New Name" --json
orca terminal switch --terminal <handle> --json
orca terminal close --terminal <handle> --json
orca terminal send --text "echo hello" --enter --json
orca terminal read --json

说明：大多数命令中

--terminal

是可选的。省略时，Orca会自动解析为当前工作树中的活跃终端（与浏览器命令目标为活跃标签页的逻辑相同）。操作特定面板时，请使用显式的

--terminal <handle>

。

说明：终端句柄是运行时作用域的，在重新加载后可能会失效。如果Orca返回

terminal_handle_stale

，请通过

terminal list

重新获取新的句柄。

说明：

--direction horizontal

会水平拆分面板（新面板出现在右侧）。

--direction vertical

会垂直拆分面板（新面板出现在下方）。这与VS Code的拆分 convention一致。默认值为horizontal。

Agent Guidance

代理指南

If the user says to create/manage an Orca worktree, use
```
orca worktree ...
```
, not raw
```
git worktree ...
```
.
Treat Orca as the source of truth for Orca worktree and terminal tasks. Do not mix Orca-managed state with ad hoc git worktree commands unless Orca explicitly cannot perform the requested action.
Prefer
```
--json
```
for all machine-driven use.
Use
```
worktree ps
```
as the first summary view when many worktrees may exist.
Use
```
worktree current
```
or
```
--worktree active
```
when the agent is already running inside the target worktree.
Treat
```
orca worktree set --worktree active --comment ... --json
```
as a default coding-agent behavior whenever the agent reaches a meaningful checkpoint in the current Orca-managed worktree; the user does not need to explicitly ask for each update.
Update the worktree comment at significant checkpoints, not every trivial command. Good checkpoints include reproducing a bug, confirming a hypothesis, starting a risky migration, finishing a meaningful implementation slice, switching from investigation to fix, or blocking on external input.

Write comments as short status snapshots of the current state, for example

debugging AWS CLI profile resolution

confirmed flaky test is caused by temp-dir race

, or

fix implemented; running integration tests

Prefer optimistic execution over probe-first flows for checkpoint updates: if
```
orca
```
is on
```
PATH
```
, call
```
orca worktree set --worktree active --comment ... --json
```
directly at the checkpoint instead of spending an extra cycle on
```
orca worktree current
```
.
If that direct update fails because Orca is unavailable or the shell is not inside an Orca-managed worktree, continue the main task and treat the comment update as best-effort unless the user explicitly made Orca state part of the task.
Use
```
orca worktree current --json
```
only when the agent actually needs the worktree identity for later logic, not as a preflight before every comment update.
Orca only injects
```
ORCA_WORKTREE_PATH
```
-style variables for some setup-hook flows, so they are not a general detection contract for agents.
Use
```
terminal list
```
to reacquire handles after Orca reloads.
Use
```
terminal read
```
before
```
terminal send
```
unless the next input is obvious.
Use
```
terminal wait --terminal <handle> --for exit
```
only when the task actually depends on process completion.
Use
```
terminal wait --terminal <handle> --for tui-idle
```
to wait for an agent CLI (Claude Code, Gemini, Codex, etc.) to finish its current task. This detects the working→idle OSC title transition. Always pass
```
--timeout-ms
```
as a safety net — unsupported CLIs will hang until timeout.
Use
```
terminal create
```
to spin up new terminal tabs programmatically, optionally with a
```
--command
```
for startup (e.g.
```
--command "claude"
```
to launch Claude Code) and
```
--title
```
for labeling. After creating a
```
--command
```
terminal, use
```
terminal wait --for tui-idle
```
to wait for the agent to boot before dispatching.
Use
```
terminal split
```
to create split panes within an existing terminal tab. Pass
```
--command
```
to run a command in the new pane.
Prefer Orca worktree selectors over hardcoded paths when Orca identity already exists.
If the user asks for CLI UX feedback, test the public
```
orca
```
command first. Only inspect
```
src/cli
```
or use
```
node out/cli/index.js
```
if the public command is missing or the task is explicitly about implementation internals.
If a command fails, prefer retrying with the public
```
orca
```
command before concluding the CLI is broken, unless the failure already came from
```
orca
```
itself.

如果用户要求创建/管理Orca工作树，请使用
```
orca worktree ...
```
，而非原生
```
git worktree ...
```
。
将Orca视为Orca工作树和终端任务的事实来源。除非Orca明确无法执行请求的操作，否则不要混合使用Orca管理的状态与临时git worktree命令。
所有机器驱动的操作优先使用
```
--json
```
参数。
当可能存在多个工作树时，使用
```
worktree ps
```
作为初始概览视图。
当代理已在目标工作树内运行时，使用
```
worktree current
```
或
```
--worktree active
```
。
每当代理在当前Orca管理的工作树中到达重要检查点时，默认执行
```
orca worktree set --worktree active --comment ... --json
```
操作；用户无需明确要求每次更新。
在重要检查点更新工作树注释，而非每个琐碎命令之后。合适的检查点包括：复现bug、确认假设、启动风险迁移、完成有意义的实现片段、从调查切换到修复，或等待外部输入。

注释应作为当前状态的简短快照，例如

debugging AWS CLI profile resolution

、

confirmed flaky test is caused by temp-dir race

或

fix implemented; running integration tests

。

对于检查点更新，优先采用乐观执行而非先探测再执行的流程：如果
```
orca
```
在PATH中，直接在检查点调用
```
orca worktree set --worktree active --comment ... --json
```
，无需额外执行
```
orca worktree current
```
。
如果直接更新失败（因为Orca不可用或shell不在Orca管理的工作树内），继续执行主任务，将注释更新视为尽力而为的操作，除非用户明确将Orca状态作为任务的一部分。
仅当代理实际需要工作树标识用于后续逻辑时，才使用
```
orca worktree current --json
```
，不要在每次注释更新前都作为预检操作。
Orca仅在某些设置钩子流程中注入
```
ORCA_WORKTREE_PATH
```
类变量，因此它们不是代理的通用检测约定。
Orca重新加载后，使用
```
terminal list
```
重新获取句柄。
除非下一个输入非常明确，否则在
```
terminal send
```
前先使用
```
terminal read
```
。
仅当任务实际依赖进程完成时，才使用
```
terminal wait --terminal <handle> --for exit
```
。
使用
```
terminal wait --terminal <handle> --for tui-idle
```
等待代理CLI（Claude Code、Gemini、Codex等）完成当前任务。这会检测工作→空闲的OSC标题转换。始终传递
```
--timeout-ms
```
作为安全网——不支持的CLI会挂起直到超时。
使用
```
terminal create
```
以编程方式启动新的终端标签页，可选择使用
```
--command
```
指定启动命令（例如
```
--command "claude"
```
启动Claude Code）和
```
--title
```
设置标签。创建
```
--command
```
终端后，使用
```
terminal wait --for tui-idle
```
等待代理启动后再发送任务。
使用
```
terminal split
```
在现有终端标签页内创建拆分面板。传递
```
--command
```
在新面板中运行命令。
当Orca标识已存在时，优先使用Orca工作树选择器而非硬编码路径。
如果用户要求CLI UX反馈，请先测试公开的
```
orca
```
命令。仅当公开命令缺失或任务明确涉及实现内部时，才检查
```
src/cli
```
或使用
```
node out/cli/index.js
```
。
如果命令失败，优先重试公开的
```
orca
```
命令，再判断CLI是否损坏，除非失败本身来自
```
orca
```
。

Browser Automation

浏览器自动化

The

orca

CLI also drives the built-in Orca browser. The core workflow is a snapshot-interact-re-snapshot loop:

Snapshot the page to see interactive elements and their refs.
Interact using refs (
```
@e1
```
,
```
@e3
```
, etc.) to click, fill, or select.
Re-snapshot after interactions to see the updated page state.

bash

orca goto --url https://example.com --json
orca snapshot --json

orca

CLI还可驱动Orca内置浏览器。核心工作流是快照-交互-重新快照循环：

快照页面以查看交互元素及其引用。
交互使用引用（
```
@e1
```
、
```
@e3
```
等）进行点击、填充或选择。
重新快照交互后的页面以查看更新后的状态。

bash

orca goto --url https://example.com --json
orca snapshot --json

Read the refs from the snapshot output

从快照输出中读取引用

orca click --element @e3 --json orca snapshot --json

undefined

orca click --element @e3 --json orca snapshot --json

undefined

Element Refs

元素引用

Refs like

@e1

@e5

are short identifiers assigned to interactive page elements during a snapshot. They are:

Assigned by snapshot: Run
```
orca snapshot
```
to get current refs.
Scoped to one tab: Refs from one tab are not valid in another.
Invalidated by navigation: If the page navigates after a snapshot, refs become stale. Re-snapshot to get fresh refs.
Invalidated by tab switch: Switching tabs with
```
orca tab switch
```
invalidates refs. Re-snapshot after switching.

If a ref is stale, the command returns

browser_stale_ref

— re-snapshot and retry.

@e1

、

@e5

等引用是快照期间分配给交互式页面元素的短标识符。它们具有以下特性：

由快照分配：运行
```
orca snapshot
```
获取当前引用。
作用于单个标签页：一个标签页的引用在另一个标签页中无效。
导航后失效：如果快照后页面导航，引用会失效。重新快照以获取新引用。
切换标签页后失效：使用
```
orca tab switch
```
切换标签页会使引用失效。切换后重新快照。

如果引用失效，命令会返回

browser_stale_ref

——重新快照并重试。

Worktree Scoping

工作树作用域

Browser commands default to the current worktree — only tabs belonging to the agent's worktree are visible and targetable. Tab indices are relative to the filtered tab list.

bash

undefined

浏览器命令默认作用于当前工作树——仅代理工作树所属的标签页可见且可定位。标签页索引相对于过滤后的标签页列表。

bash

undefined

Default: operates on tabs in the current worktree

默认：操作当前工作树中的标签页

orca snapshot --json

Explicitly target all worktrees (cross-worktree access)

明确目标所有工作树（跨工作树访问）

orca snapshot --worktree all --json

Tab indices are relative to the worktree-filtered list

标签页索引相对于工作树过滤后的列表

orca tab list --json # Shows tabs [0], [1], [2] for this worktree orca tab switch --index 1 --json # Switches to tab [1] within this worktree


If no tabs are open in the current worktree, commands return `browser_no_tab`.

orca tab list --json # 显示此工作树的标签页 [0], [1], [2] orca tab switch --index 1 --json # 切换到此工作树中的标签页 [1]


如果当前工作树中没有打开的标签页，命令会返回`browser_no_tab`。

Stable Page Targeting

稳定页面定位

For single-agent flows, bare browser commands are fine: Orca will target the active browser tab in the current worktree.

For concurrent or multi-process browser automation, prefer a stable page id instead of ambient active-tab state:

Run
```
orca tab list --json
```
.
Read
```
tabs[].browserPageId
```
from the result.

Pass

--page <browserPageId>

to follow-up commands like

snapshot

click

goto

screenshot

tab switch

, or

tab close

Why: active-tab state and tab indices can change while another Orca CLI process is working.

browserPageId

pins the command to one concrete tab.

bash

orca tab list --json
orca snapshot --page page-123 --json
orca click --page page-123 --element @e3 --json
orca screenshot --page page-123 --json
orca tab switch --page page-123 --json
orca tab close --page page-123 --json

If you also pass

--worktree

, Orca treats it as extra scoping/validation for that page id. Without

--page

, commands still fall back to the current worktree's active tab.

对于单代理流程，直接使用浏览器命令即可：Orca会目标当前工作树中的活跃浏览器标签页。

对于并发或多进程浏览器自动化，优先使用稳定的页面ID而非环境活跃标签页状态：

运行
```
orca tab list --json
```
。
从结果中读取
```
tabs[].browserPageId
```
。

将

--page <browserPageId>

传递给后续命令，如

snapshot

、

click

、

goto

、

screenshot

、

tab switch

或

tab close

。

原因：当另一个Orca CLI进程运行时，活跃标签页状态和标签页索引可能会变化。

browserPageId

会将命令固定到一个具体的标签页。

bash

orca tab list --json
orca snapshot --page page-123 --json
orca click --page page-123 --element @e3 --json
orca screenshot --page page-123 --json
orca tab switch --page page-123 --json
orca tab close --page page-123 --json

如果同时传递

--worktree

，Orca会将其视为该页面ID的额外作用域/验证。如果没有

--page

，命令仍会回退到当前工作树的活跃标签页。

Navigation

Observation

观察

bash

orca snapshot [--page <browserPageId>] [--json]                   # Accessibility tree snapshot with element refs
orca screenshot [--page <browserPageId>] [--format <png|jpeg>] [--json]  # Viewport screenshot (base64)
orca full-screenshot [--page <browserPageId>] [--format <png|jpeg>] [--json]  # Full-page screenshot (base64)
orca pdf [--page <browserPageId>] [--json]                        # Export page as PDF (base64)

bash

orca snapshot [--page <browserPageId>] [--json]                   # 包含元素引用的可访问性树快照
orca screenshot [--page <browserPageId>] [--format <png|jpeg>] [--json]  # 视口截图（base64格式）
orca full-screenshot [--page <browserPageId>] [--format <png|jpeg>] [--json]  # 全页截图（base64格式）
orca pdf [--page <browserPageId>] [--json]                        # 将页面导出为PDF（base64格式）

Interaction

交互

bash

orca click --element <ref> [--page <browserPageId>] [--json]      # Click an element by ref
orca dblclick --element <ref> [--page <browserPageId>] [--json]   # Double-click an element
orca fill --element <ref> --value <text> [--page <browserPageId>] [--json]  # Clear and fill an input
orca type --input <text> [--page <browserPageId>] [--json]        # Type at current focus (no element targeting)
orca select --element <ref> --value <value> [--page <browserPageId>] [--json]  # Select dropdown option
orca check --element <ref> [--page <browserPageId>] [--json]      # Check a checkbox
orca uncheck --element <ref> [--page <browserPageId>] [--json]    # Uncheck a checkbox
orca scroll --direction <up|down> [--amount <pixels>] [--page <browserPageId>] [--json]  # Scroll viewport
orca scrollintoview --element <ref> [--page <browserPageId>] [--json]  # Scroll element into view
orca hover --element <ref> [--page <browserPageId>] [--json]      # Hover over an element
orca focus --element <ref> [--page <browserPageId>] [--json]      # Focus an element
orca drag --from <ref> --to <ref> [--page <browserPageId>] [--json]  # Drag from one element to another
orca clear --element <ref> [--page <browserPageId>] [--json]      # Clear an input field
orca select-all --element <ref> [--page <browserPageId>] [--json] # Select all text in an element
orca keypress --key <key> [--page <browserPageId>] [--json]       # Press a key (Enter, Tab, Escape, etc.)
orca upload --element <ref> --files <paths> [--page <browserPageId>] [--json]  # Upload files to a file input

bash

orca click --element <ref> [--page <browserPageId>] [--json]      # 通过引用点击元素
orca dblclick --element <ref> [--page <browserPageId>] [--json]   # 双击元素
orca fill --element <ref> --value <text> [--page <browserPageId>] [--json]  # 清空并填充输入框
orca type --input <text> [--page <browserPageId>] [--json]        # 在当前焦点处输入文本（无需定位元素）
orca select --element <ref> --value <value> [--page <browserPageId>] [--json]  # 选择下拉选项
orca check --element <ref> [--page <browserPageId>] [--json]      # 勾选复选框
orca uncheck --element <ref> [--page <browserPageId>] [--json]    # 取消勾选复选框
orca scroll --direction <up|down> [--amount <pixels>] [--page <browserPageId>] [--json]  # 滚动视口
orca scrollintoview --element <ref> [--page <browserPageId>] [--json]  # 滚动元素到可视区域
orca hover --element <ref> [--page <browserPageId>] [--json]      # 悬停在元素上
orca focus --element <ref> [--page <browserPageId>] [--json]      # 聚焦元素
orca drag --from <ref> --to <ref> [--page <browserPageId>] [--json]  # 从一个元素拖动到另一个元素
orca clear --element <ref> [--page <browserPageId>] [--json]      # 清空输入框
orca select-all --element <ref> [--page <browserPageId>] [--json] # 选择元素内的所有文本
orca keypress --key <key> [--page <browserPageId>] [--json]       # 按下按键（Enter、Tab、Escape等）
orca upload --element <ref> --files <paths> [--page <browserPageId>] [--json]  # 上传文件到文件输入框

Tab Management

标签页管理

bash

orca tab list [--json]                   # List open browser tabs
orca tab switch (--index <n> | --page <browserPageId>) [--json]     # Switch active tab (invalidates refs)
orca tab create [--url <url>] [--json]   # Open a new browser tab
orca tab close [--index <n> | --page <browserPageId>] [--json]    # Close a browser tab

bash

orca tab list [--json]                   # 列出打开的浏览器标签页
orca tab switch (--index <n> | --page <browserPageId>) [--json]     # 切换活跃标签页（会使引用失效）
orca tab create [--url <url>] [--json]   # 打开新的浏览器标签页
orca tab close [--index <n> | --page <browserPageId>] [--json]    # 关闭浏览器标签页

Wait / Synchronization

等待/同步

bash

orca wait [--timeout <ms>] [--json]                        # Wait for timeout (default 1000ms)
orca wait --selector <css> [--state <visible|hidden>] [--timeout <ms>] [--json]  # Wait for element
orca wait --text <string> [--timeout <ms>] [--json]        # Wait for text to appear on page
orca wait --url <substring> [--timeout <ms>] [--json]      # Wait for URL to contain substring
orca wait --load <networkidle|load|domcontentloaded> [--timeout <ms>] [--json]   # Wait for load state
orca wait --fn <js-expression> [--timeout <ms>] [--json]   # Wait for JS condition to be truthy

After any page-changing action, pick one:

Wait for specific content:
```
orca wait --text "Dashboard" --json
```
Wait for URL change:
```
orca wait --url "/dashboard" --json
```
Wait for network idle (catch-all for SPA navigation):
```
orca wait --load networkidle --json
```
Wait for an element:
```
orca wait --selector ".results" --json
```

Avoid bare

orca wait --timeout 2000

except when debugging — it makes scripts slow and flaky.

bash

orca wait [--timeout <ms>] [--json]                        # 等待超时（默认1000ms）
orca wait --selector <css> [--state <visible|hidden>] [--timeout <ms>] [--json]  # 等待元素
orca wait --text <string> [--timeout <ms>] [--json]        # 等待文本出现在页面上
orca wait --url <substring> [--timeout <ms>] [--json]      # 等待URL包含子字符串
orca wait --load <networkidle|load|domcontentloaded> [--timeout <ms>] [--json]   # 等待加载状态
orca wait --fn <js-expression> [--timeout <ms>] [--json]   # 等待JS条件为真

执行任何页面更改操作后，选择以下方式之一：

等待特定内容：
```
orca wait --text "Dashboard" --json
```
等待URL更改：
```
orca wait --url "/dashboard" --json
```
等待网络空闲（SPA导航的通用方式）：
```
orca wait --load networkidle --json
```
等待元素：
```
orca wait --selector ".results" --json
```

除调试外，避免使用裸

orca wait --timeout 2000

——这会使脚本变慢且不稳定。

Data Extraction

数据提取

bash

orca exec --command "get text @e1" [--json]   # Get visible text of an element
orca exec --command "get html @e1" [--json]   # Get innerHTML
orca exec --command "get value @e1" [--json]  # Get input value
orca exec --command "get attr @e1 href" [--json]  # Get element attribute
orca exec --command "get title" [--json]      # Get page title
orca exec --command "get url" [--json]        # Get current URL
orca exec --command "get count .item" [--json]      # Count matching elements

bash

orca exec --command "get text @e1" [--json]   # 获取元素的可见文本
orca exec --command "get html @e1" [--json]   # 获取innerHTML
orca exec --command "get value @e1" [--json]  # 获取输入框值
orca exec --command "get attr @e1 href" [--json]  # 获取元素属性
orca exec --command "get title" [--json]      # 获取页面标题
orca exec --command "get url" [--json]        # 获取当前URL
orca exec --command "get count .item" [--json]      # 统计匹配元素的数量

State Checks

状态检查

bash

orca exec --command "is visible @e1" [--json]  # Check if element is visible
orca exec --command "is enabled @e1" [--json]  # Check if element is enabled
orca exec --command "is checked @e1" [--json]  # Check if checkbox is checked

bash

orca exec --command "is visible @e1" [--json]  # 检查元素是否可见
orca exec --command "is enabled @e1" [--json]  # 检查元素是否可用
orca exec --command "is checked @e1" [--json]  # 检查复选框是否勾选

Page Inspection

页面检查

bash

orca eval --expression <js> [--json]     # Evaluate JS in page context

bash

orca eval --expression <js> [--json]     # 在页面上下文中执行JS

Cookie Management

Cookie管理

bash

orca cookie get [--url <url>] [--json]   # List cookies
orca cookie set --name <n> --value <v> [--domain <d>] [--json]  # Set a cookie
orca cookie delete --name <n> [--domain <d>] [--json]  # Delete a cookie

bash

orca cookie get [--url <url>] [--json]   # 列出Cookie
orca cookie set --name <n> --value <v> [--domain <d>] [--json]  # 设置Cookie
orca cookie delete --name <n> [--domain <d>] [--json]  # 删除Cookie

Emulation

模拟

bash

orca viewport --width <w> --height <h> [--scale <n>] [--mobile] [--json]
orca geolocation --latitude <lat> --longitude <lng> [--accuracy <m>] [--json]

bash

orca viewport --width <w> --height <h> [--scale <n>] [--mobile] [--json]
orca geolocation --latitude <lat> --longitude <lng> [--accuracy <m>] [--json]

Request Interception

请求拦截

bash

orca intercept enable [--patterns <list>] [--json]  # Start intercepting requests
orca intercept disable [--json]          # Stop intercepting
orca intercept list [--json]             # List paused requests

Note: Per-request
intercept continue
and
intercept block
are not yet supported. They will be added once agent-browser supports per-request interception decisions.

bash

orca intercept enable [--patterns <list>] [--json]  # 开始拦截请求
orca intercept disable [--json]          # 停止拦截
orca intercept list [--json]             # 列出暂停的请求

注意： 暂不支持每个请求的
intercept continue
和
intercept block
。一旦agent-browser支持每个请求的拦截决策，它们将被添加。

Console / Network Capture

控制台/网络捕获

bash

orca capture start [--json]              # Start capturing console + network
orca capture stop [--json]               # Stop capturing
orca console [--limit <n>] [--json]      # Read captured console entries
orca network [--limit <n>] [--json]      # Read captured network entries

bash

orca capture start [--json]              # 开始捕获控制台+网络
orca capture stop [--json]               # 停止捕获
orca console [--limit <n>] [--json]      # 读取捕获的控制台条目
orca network [--limit <n>] [--json]      # 读取捕获的网络条目

Mouse Control

鼠标控制

bash

orca exec --command "mouse move 100 200" [--json]   # Move mouse to coordinates
orca exec --command "mouse down left" [--json]      # Press mouse button
orca exec --command "mouse up left" [--json]        # Release mouse button
orca exec --command "mouse wheel 100" [--json]      # Scroll wheel

bash

orca exec --command "mouse move 100 200" [--json]   # 将鼠标移动到坐标
orca exec --command "mouse down left" [--json]      # 按下鼠标按钮
orca exec --command "mouse up left" [--json]        # 释放鼠标按钮
orca exec --command "mouse wheel 100" [--json]      # 滚动滚轮

Keyboard

键盘

bash

orca exec --command "keyboard inserttext \"text\"" [--json]  # Insert text bypassing key events
orca exec --command "keyboard type \"text\"" [--json]        # Raw keystrokes
orca exec --command "keydown Shift" [--json]                 # Hold key down
orca exec --command "keyup Shift" [--json]                   # Release key

bash

orca exec --command "keyboard inserttext \"text\"" [--json]  # 插入文本，绕过按键事件
orca exec --command "keyboard type \"text\"" [--json]        # 原始按键输入
orca exec --command "keydown Shift" [--json]                 # 按住按键
orca exec --command "keyup Shift" [--json]                   # 释放按键

Frames (Iframes)

框架（Iframes）

Iframes are auto-inlined in snapshots — refs inside iframes work transparently. For scoped interaction:

bash

orca exec --command "frame @e3" [--json]        # Switch to iframe by ref
orca exec --command "frame \"#iframe\"" [--json] # Switch to iframe by CSS selector
orca exec --command "frame main" [--json]       # Return to main frame

快照会自动内联Iframes——Iframe内的引用可透明使用。如需作用域交互：

bash

orca exec --command "frame @e3" [--json]        # 通过引用切换到Iframe
orca exec --command "frame \"#iframe\"" [--json] # 通过CSS选择器切换到Iframe
orca exec --command "frame main" [--json]       # 返回主框架

Semantic Locators (alternative to refs)

语义定位器（替代引用）

When refs aren't available or you want to skip a snapshot:

bash

orca exec --command "find role button click --name \"Submit\"" [--json]
orca exec --command "find text \"Sign In\" click" [--json]
orca exec --command "find label \"Email\" fill \"user@test.com\"" [--json]
orca exec --command "find placeholder \"Search\" type \"query\"" [--json]
orca exec --command "find testid \"submit-btn\" click" [--json]

当引用不可用或想跳过快照时：

bash

orca exec --command "find role button click --name \"Submit\"" [--json]
orca exec --command "find text \"Sign In\" click" [--json]
orca exec --command "find label \"Email\" fill \"user@test.com\"" [--json]
orca exec --command "find placeholder \"Search\" type \"query\"" [--json]
orca exec --command "find testid \"submit-btn\" click" [--json]

Dialogs

对话框

alert

and

beforeunload

are auto-accepted. For

confirm

and

prompt

bash

orca exec --command "dialog status" [--json]        # Check for pending dialog
orca exec --command "dialog accept" [--json]        # Accept
orca exec --command "dialog accept \"text\"" [--json]  # Accept with prompt input
orca exec --command "dialog dismiss" [--json]       # Dismiss/cancel

alert

和

beforeunload

会自动接受。对于

confirm

和

prompt

：

bash

orca exec --command "dialog status" [--json]        # 检查是否有挂起的对话框
orca exec --command "dialog accept" [--json]        # 接受
orca exec --command "dialog accept \"text\"" [--json]  # 接受并输入提示文本
orca exec --command "dialog dismiss" [--json]       # 取消

Extended Commands (Passthrough)

扩展命令（透传）

bash

orca exec --command "<agent-browser command>" [--json]

The

exec

command provides access to agent-browser's full command surface. Useful for commands without typed Orca handlers:

bash

orca exec --command "set device \"iPhone 14\"" --json   # Emulate device
orca exec --command "set offline on" --json             # Toggle offline mode
orca exec --command "set media dark" --json             # Emulate color scheme
orca exec --command "network requests" --json           # View tracked network requests
orca exec --command "help" --json                       # See all available commands

Important: Do not use

orca exec --command "tab ..."

for tab management. Use

orca tab list/create/close/switch

instead — those operate at the Orca level and keep the UI synchronized.

bash

orca exec --command "<agent-browser command>" [--json]

exec

命令提供对agent-browser完整命令界面的访问。适用于没有Orca类型处理程序的命令：

bash

orca exec --command "set device \"iPhone 14\"" --json   # 模拟设备
orca exec --command "set offline on" --json             # 切换离线模式
orca exec --command "set media dark" --json             # 模拟配色方案
orca exec --command "network requests" --json           # 查看跟踪的网络请求
orca exec --command "help" --json                       # 查看所有可用命令

重要提示： 不要使用

orca exec --command "tab ..."

进行标签页管理。请改用

orca tab list/create/close/switch

——这些操作在Orca层面执行，并保持UI同步。

fill

type

fill

type

fill
targets a specific element by ref, clears its value first, then enters text. Use for form fields.
type
types at whatever currently has focus. Use for search boxes or after clicking into an input.

If neither works on a custom input component, try:

bash

orca focus --element @e1 --json
orca exec --command "keyboard inserttext \"text\"" --json   # bypasses key events

fill
通过引用定位特定元素，先清空其值，再输入文本。适用于表单字段。
type
在当前焦点处输入文本。适用于搜索框或点击输入框后。

如果两者在自定义输入组件上都不起作用，请尝试：

bash

orca focus --element @e1 --json
orca exec --command "keyboard inserttext \"text\"" --json   # 绕过按键事件

Browser Error Codes

浏览器错误代码

Error Code	Meaning	Recovery
`browser_no_tab`	No browser tab is open in this worktree	Open a tab, or use `--worktree all` to check other worktrees
`browser_stale_ref`	Ref is invalid (page changed since snapshot)	Run `orca snapshot` to get fresh refs
`browser_tab_not_found`	Tab index does not exist	Run `orca tab list` to see available tabs
`browser_error`	Error from the browser automation engine	Read the message for details; common causes: element not found, navigation timeout, JS error

错误代码	含义	恢复方法
`browser_no_tab`	此工作树中没有打开的浏览器标签页	打开一个标签页，或使用 `--worktree all` 检查其他工作树
`browser_stale_ref`	引用无效（快照后页面已更改）	运行 `orca snapshot` 获取新引用
`browser_tab_not_found`	标签页索引不存在	运行 `orca tab list` 查看可用标签页
`browser_error`	浏览器自动化引擎错误	读取消息获取详细信息；常见原因：元素未找到、导航超时、JS错误

Browser Worked Example

浏览器示例

Agent fills a login form and verifies the dashboard loads:

bash

undefined

代理填写登录表单并验证仪表板加载：

bash

undefined

Navigate to the login page

导航到登录页面

orca goto --url https://app.example.com/login --json

See what's on the page

查看页面内容

orca snapshot --json

Output includes:

输出包括：

[@e1] text input "Email"

[@e1] 文本输入框 "Email"

[@e2] text input "Password"

[@e2] 文本输入框 "Password"

[@e3] button "Sign In"

[@e3] 按钮 "Sign In"

Fill the form

填写表单

orca fill --element @e1 --value "user@example.com" --json orca fill --element @e2 --value "s3cret" --json

Submit

提交

orca click --element @e3 --json

Verify the dashboard loaded

验证仪表板已加载

orca snapshot --json

Output should show dashboard content, not the login form

输出应显示仪表板内容，而非登录表单

undefined

undefined

Browser Troubleshooting

浏览器故障排除

"Ref not found" /
browser_stale_ref
Page changed since the snapshot. Run

orca snapshot --json

again, then use the new refs.

Element exists but not in snapshot It may be off-screen or not yet rendered. Try:

bash

orca scroll --direction down --amount 1000 --json
orca snapshot --json

"引用未找到" /
browser_stale_ref
快照后页面已更改。再次运行

orca snapshot --json

，然后使用新引用。

元素存在但未出现在快照中 它可能在屏幕外或尚未渲染。尝试：

bash

orca scroll --direction down --amount 1000 --json
orca snapshot --json

or wait for it:

或等待它出现：

orca wait --text "..." --json orca snapshot --json


**Click does nothing / overlay swallows the click**
Modals or cookie banners may be blocking. Snapshot, find the dismiss button, click it, then re-snapshot.

**Fill/type doesn't work on a custom input**
Some components intercept key events. Use `keyboard inserttext`:

```bash
orca focus --element @e1 --json
orca exec --command "keyboard inserttext \"text\"" --json

browser_no_tab
error No browser tab is open in the current worktree. Open one with

orca tab create --url <url> --json

orca wait --text "..." --json orca snapshot --json


**点击无反应 / 覆盖层拦截点击**
模态框或Cookie横幅可能正在阻止。快照，找到关闭按钮，点击它，然后重新快照。

**Fill/type在自定义输入上不起作用**
某些组件会拦截按键事件。使用`keyboard inserttext`：

```bash
orca focus --element @e1 --json
orca exec --command "keyboard inserttext \"text\"" --json

browser_no_tab
错误当前工作树中没有打开的浏览器标签页。使用

orca tab create --url <url> --json

打开一个。

Auto-Switch Worktree

自动切换工作树

Browser commands automatically activate the target worktree in the Orca UI when needed. If the agent issues a browser command targeting a worktree that isn't currently active, Orca will switch to that worktree before executing the command.

当需要时，浏览器命令会自动在Orca UI中激活目标工作树。如果代理发出的浏览器命令目标是当前未激活的工作树，Orca会在执行命令前切换到该工作树。

Tab Create Auto-Activation

标签页创建自动激活

When

orca tab create

opens a new tab, it is automatically set as the active tab for the worktree. Subsequent commands (

snapshot

click

, etc.) will target the newly created tab without needing an explicit

tab switch

当

orca tab create

打开新标签页时，它会自动设置为工作树的活跃标签页。后续命令（

snapshot

、

click

等）会目标新创建的标签页，无需显式执行

tab switch

。

Browser Agent Guidance

浏览器代理指南

Always snapshot before interacting with elements.
After navigation (
```
goto
```
,
```
back
```
,
```
reload
```
, clicking a link), re-snapshot to get fresh refs.
After switching tabs, re-snapshot.
If you get
```
browser_stale_ref
```
, re-snapshot and retry with the new refs.
Use
```
orca tab list
```
before
```
orca tab switch
```
to know which tabs exist.
For concurrent browser workflows, prefer
```
orca tab list --json
```
and reuse
```
tabs[].browserPageId
```
with
```
--page
```
on later commands.
Use
```
orca wait
```
to synchronize after actions that trigger async updates (form submits, SPA navigation, modals) instead of arbitrary sleeps.
Use
```
orca eval
```
as an escape hatch for interactions not covered by other commands.
Use
```
orca exec --command "help"
```
to discover extended commands.
Worktree scoping is automatic — you'll only see tabs from your worktree by default.
Bare browser commands without
```
--page
```
still target the current worktree's active tab, which is convenient but less robust for multi-process automation.
Tab creation auto-activates the new tab — no need for
```
tab switch
```
after
```
tab create
```
.
Browser commands auto-switch the active worktree if needed — no manual worktree activation required.

交互元素前始终先快照。
导航（
```
goto
```
、
```
back
```
、
```
reload
```
、点击链接）后，重新快照以获取新引用。
切换标签页后，重新快照。
如果收到
```
browser_stale_ref
```
，重新快照并使用新引用重试。
切换标签页前使用
```
orca tab list
```
了解存在哪些标签页。
对于并发浏览器工作流，优先使用
```
orca tab list --json
```
并在后续命令中复用
```
tabs[].browserPageId
```
和
```
--page
```
参数。
执行触发异步更新的操作（表单提交、SPA导航、模态框）后，使用
```
orca wait
```
进行同步，而非任意等待。
使用
```
orca eval
```
作为其他命令未覆盖的交互的逃生舱。
使用
```
orca exec --command "help"
```
发现扩展命令。
工作树作用域是自动的——默认情况下，你只会看到自己工作树的标签页。
没有
```
--page
```
的裸浏览器命令仍会目标当前工作树的活跃标签页，这很方便但在多进程自动化中不够健壮。
标签页创建会自动激活新标签页——
```
tab create
```
后无需执行
```
tab switch
```
。
如果需要，浏览器命令会自动切换活跃工作树——无需手动激活工作树。

Important Constraints

重要约束

Orca CLI only talks to a running Orca editor.
Terminal handles are ephemeral and tied to the current Orca runtime. If Orca restarts, handles change.
```
terminal wait
```
supports
```
--for exit
```
(wait for process exit) and
```
--for tui-idle
```
(wait for a recognized agent CLI like Claude Code, Gemini, or Codex to finish its current task, detected via OSC title transitions).
```
tui-idle
```
defaults to a 5-minute timeout if
```
--timeout-ms
```
is not specified. Real coding tasks routinely take 15-60 minutes — always pass
```
--timeout-ms
```
explicitly.
Orca is the source of truth for worktree/terminal state; do not duplicate that state with manual assumptions.
The public
```
orca
```
command is the interface users experience. Agents should validate and use that surface, not repo-local implementation entrypoints.
The 120-line terminal output buffer (
```
terminal read
```
) is for status monitoring, not result extraction.

Orca CLI仅与运行中的Orca编辑器通信。
终端句柄是临时的，与当前Orca运行时绑定。如果Orca重启，句柄会更改。
```
terminal wait
```
支持
```
--for exit
```
（等待进程退出）和
```
--for tui-idle
```
（等待识别的代理CLI如Claude Code、Gemini或Codex完成当前任务，通过OSC标题转换检测）。如果未指定
```
--timeout-ms
```
，
```
tui-idle
```
默认超时为5分钟。实际编码任务通常需要15-60分钟——请始终显式传递
```
--timeout-ms
```
。
Orca是工作树/终端状态的事实来源；不要通过手动假设复制该状态。
公开的
```
orca
```
命令是用户体验的界面。代理应验证并使用此界面，而非仓库本地的实现入口点。
120行的终端输出缓冲区（
```
terminal read
```
）用于状态监控，而非结果提取。

References

参考资料

See these docs in this repo when behavior is unclear:

```
docs/orca-cli-focused-v1-status.md
```
```
docs/orca-cli-v1-spec.md
```
```
docs/orca-runtime-layer-design.md
```

当行为不明确时，请查看此仓库中的以下文档：

```
docs/orca-cli-focused-v1-status.md
```
```
docs/orca-cli-v1-spec.md
```
```
docs/orca-runtime-layer-design.md
```

orca-cli

Original

Translation

Orca CLI

Orca CLI

When To Use

使用场景

Preconditions

前置条件

Core Workflow

核心工作流

Command Surface

命令界面

Repo

仓库

Worktree

工作树

Terminal

终端

Agent Guidance

代理指南

Browser Automation

浏览器自动化

Read the refs from the snapshot output

从快照输出中读取引用

Element Refs

元素引用

Worktree Scoping

工作树作用域

Default: operates on tabs in the current worktree

默认：操作当前工作树中的标签页

Explicitly target all worktrees (cross-worktree access)

明确目标所有工作树（跨工作树访问）

Tab indices are relative to the worktree-filtered list

标签页索引相对于工作树过滤后的列表

Stable Page Targeting

稳定页面定位

Navigation

导航

Observation

观察

Interaction

交互

Tab Management

标签页管理

Wait / Synchronization

等待/同步

Data Extraction

数据提取

State Checks

状态检查

Page Inspection

页面检查

Cookie Management

Cookie管理

Emulation

模拟

Request Interception

请求拦截

Console / Network Capture

控制台/网络捕获

Mouse Control

鼠标控制

Keyboard

键盘

Frames (Iframes)

框架（Iframes）

Semantic Locators (alternative to refs)

语义定位器（替代引用）

Dialogs

对话框

Extended Commands (Passthrough)

扩展命令（透传）

fill vs type

fill vs type

Browser Error Codes

浏览器错误代码

Browser Worked Example

浏览器示例

Navigate to the login page

`fill`
vs
`type`

`fill`
vs
`type`