orca-cli

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.

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

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:

command -v orca

Then use the public command:

orca status --json

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

command -v orca
orca status --json

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

orca worktree current --json

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

Core Workflow

1. Confirm Orca runtime availability:

orca status --json

If Orca is not running yet:

orca open --json
orca status --json

2. Discover current Orca state:

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

3. Resolve a target worktree or terminal handle.

4. Act through Orca:

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

5. 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:

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.

Command Surface

Repo

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

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

Terminal

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

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.

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. In local Orca sessions, --command "codex" is routed through Orca's visible terminal path automatically so Codex does not start as a headless/background PTY. 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.

Browser Automation

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

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

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

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.

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.

# 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.

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:

1. Run orca tab list --json.
2. Read tabs[].browserPageId from the result.
3. 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.

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.

Navigation

orca goto --url <url> [--json]           # Navigate to URL, waits for page load
orca back [--json]                       # Go back in browser history
orca forward [--json]                    # Go forward in browser history
orca reload [--json]                     # Reload the current page

Observation

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)

Interaction

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

Tab Management

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>] [--js

...