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
reading and replying to Orca-managed 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
finding the Claude Code terminal for a worktree and replying to it
checking which Orca worktrees have live terminal activity

orca

适用于以下场景：

运行中的Orca应用内的工作树编排
读取和回复Orca管理的终端
停止或等待Orca管理的终端
访问Orca已知的仓库

当普通shell工具更简单，且Orca状态不影响任务时，不要使用

orca

。

示例：

为每个GitHub issue创建一个Orca工作树
找到对应工作树的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.

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

orca

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

优先使用公开的
```
orca
```
命令
Orca编辑器/运行时应已启动，否则Agent需要通过
```
orca open
```
启动它
不要一开始为了确定如何调用CLI就去检查Orca源码文件，第一步应先检查是否已安装
```
orca
```
命令。

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

bash

command -v orca

然后使用公开命令：

bash

orca status --json

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

bash

command -v orca
orca status --json

如果PATH中没有

orca

，请明确告知用户，停止操作或要求用户先安装/注册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
```

确认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
```

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 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 rm --worktree id:<worktreeId> --force --json

Worktree selectors supported in focused v1:

```
id:<worktree-id>
```
```
path:<absolute-path>
```
```
branch:<branch-name>
```
```
issue:<number>
```

bash

orca worktree list --repo id:<repoId> --json
orca worktree ps --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 rm --worktree id:<worktreeId> --force --json

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

```
id:<worktree-id>
```
```
path:<absolute-path>
```
```
branch:<branch-name>
```
```
issue:<number>
```

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 stop --worktree id:<worktreeId> --json

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

使用选择器查找终端，然后使用返回的句柄进行后续的实时交互。

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 stop --worktree id:<worktreeId> --json

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

terminal_handle_stale

，请通过

terminal list

重新获取新的句柄。

Agent Guidance

Agent使用指南

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
```
terminal list
```
to reacquire handles after Orca reloads.
Use
```
terminal read
```
before
```
terminal send
```
unless the next input is obvious.
Use
```
terminal wait --for exit
```
only when the task actually depends on process completion.
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管理的状态和临时的git工作树命令，除非Orca明确无法执行请求的操作。
所有机器调用场景优先使用
```
--json
```
参数。
当存在大量工作树时，优先使用
```
worktree ps
```
获取概览视图。
Orca重载后使用
```
terminal list
```
重新获取句柄。
在
```
terminal send
```
之前先执行
```
terminal read
```
，除非下一步输入是明确的。
仅当任务确实依赖进程完成时，才使用
```
terminal wait --for exit
```
。
当Orca中已存在身份标识时，优先使用Orca工作树选择器，而非硬编码路径。
如果用户要求CLI UX反馈，请先测试公开的
```
orca
```
命令。仅当公开命令缺失，或任务明确涉及实现内部细节时，才检查
```
src/cli
```
或使用
```
node out/cli/index.js
```
。
如果命令失败，优先重试公开的
```
orca
```
命令，再判定CLI损坏，除非失败本身就来自
```
orca
```
命令。

Important Constraints

重要约束

Orca CLI only talks to a running Orca editor.
Terminal handles are ephemeral and tied to the current Orca runtime.
```
terminal wait
```
in focused v1 supports only
```
--for exit
```
.
Orca is the source of truth for worktree/terminal orchestration; 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.

Orca CLI仅与运行中的Orca编辑器通信。
终端句柄是临时的，与当前Orca运行时绑定。
v1聚焦版本的
```
terminal wait
```
仅支持
```
--for exit
```
。
Orca是工作树/终端编排的唯一可信数据源；不要通过手动假设复制该状态。
公开的
```
orca
```
命令是用户实际使用的接口。Agent应验证并使用该接口，不要使用代码库本地的实现入口点。

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
```