orca-cli

Orca CLI

🧭 ディスパッチバックエンド — 安価なエージェント／モデルを選び、複数のワーカーを並列で実行し、opencode／オーケストレーションの構文を使う場合は、orca-dispatch-reference を参照してください（唯一の信頼できる情報源です。ここで構文を重複して記載しないでください）。

Orca の実行中のエディター／ランタイムを信頼できる情報源として使う場合は、orca を使用してください。Linux では、このファイルで orca と記載されている箇所では orca-ide を使用してください。

Orca の状態が関係しない場合は、通常のシェルツールを使用してください。

Start Here

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

エージェントから呼び出す場合は、--json を優先してください。CLI が見つからない場合は、最初にソースファイルを調べるのではなく、そのことを明確に伝えてください。

Worktrees

Orca のワークツリー／ワークスペースは、リポジトリのチェックアウト、メタデータ、ターミナル、ブラウザータブ、UI 状態を Orca が追跡したビューです。

一般的なコマンド：

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>
• シェルの cwd から見た、外側の Orca 管理ワークツリーを指定する場合は active／current

系譜のルール：

• Orca 管理ワークツリー内から作成する場合、可能であれば Orca は現在のワークスペースを親として推定します。
• 子との関係を明示する場合は、--parent-worktree active を使用してください。
• 新しい作業が独立している場合に限り、--no-parent を使用してください。
• --repo を省略すると、可能な場合は Orca が現在の Orca ワークツリーからリポジトリを推定します。

エージェント／セットアップのフラグ：

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> は最初のターミナルでそのエージェントを起動します。--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 を実行してください。

Worktree Comments

ワークツリーコメントは、進捗をすばやく確認できるよう、Orca のワークスペース一覧／カードに表示される短いステータステキストです。

コーディングエージェントは、重要なチェックポイントでアクティブなワークツリーのコメントを更新してください。

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

再現、修正、検証、引き継ぎ、ブロッカーなど、状態に重要な変更があった後に更新してください。コメントは短く、最新の状態に保ってください。Orca の状態が求められていない場合、更新に失敗しても問題ありません。

Terminals

一般的なコマンド：

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 send の前に terminal read を使用してください。
• タスクの状態、受信箱、返信の追跡が不要な直接のターミナル入力や単発のプロンプトに限り、terminal send を使用してください。
• 構造化された連携には orchestration スキルを呼び出してください。このスキルは、メッセージ、引き継ぎ、タスク DAG、ディスパッチ、受信箱／返信フロー、コーディネーターループに orca orchestration ... コマンドを使用します。
• Claude Code、Gemini、Codex などのエージェント 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> を使用し、--day <0-6> は日曜日を 0 とする weekly の場合にのみ使用してください。

実行ごとに新しいワークツリーを作成するには --repo <selector> を、既存の Orca ワークツリーを使うには --workspace <selector> または --workspace-mode existing を使用してください。--repo と --workspace は同時に指定できません。既存のワークスペースを使う自動化の場合に限り、--reuse-session を使用してください。前回のターミナルがなくなっている場合、Orca は新しいセッションに切り替えます。セットアップのテスト中は --disabled を使用してください。

組み込みブラウザー

組み込みブラウザーは Orca に埋め込まれたブラウザータブで、Orca のワークツリー内に限定されます。Chrome／Safari やデスクトップアプリの UI ではありません。

これらのコマンドで操作できるのは、Orca に埋め込まれたブラウザータブのみです。外部の Chrome／Safari／WebView、または Orca アプリの画面や設定を操作する場合は、Computer Use スキル／ツールを使用してください。ユーザーが Orca の CLI によるデスクトップ操作を明示的に依頼した場合は、orca computer ... を使用してください。デスクトップ UI の操作にブラウザーコマンドを使わないでください。

スナップショットを取得し、操作してから再度スナップショットを取得するループを使用してください。

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 によって割り当てられ、1 つのタブに限定されます。ナビゲーションまたはタブの切り替え後は無効になります。
• ブラウザーコマンドは、デフォルトで現在のワークツリーとそのアクティブなタブを対象にします。--worktree all は意図した場合にのみ使用してください。
• ブラウザーを並行して操作する場合は、orca tab list --json を実行して tabs[].browserPageId を確認し、後続のコマンドで --page <browserPageId> を指定してください。
• Orca が UI の状態を同期できるよう、orca exec --command "tab ..." ではなく、型指定されたタブコマンド（orca tab list/create/close/switch）を使用してください。
• 非同期のページ変更後は、単純なタイムアウトではなく、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。