Orca CLI reference

Commands, selectors, and agent-friendly patterns for driving Orca from a shell.

The orca CLI talks to a running Orca runtime. Use it when a shell script or agent needs to inspect worktrees, launch terminals, open files, automate the built-in browser, or report progress back into Orca.

Verify the runtime

command -v orca
orca status --json

If Orca is not already running:

orca open --json
orca status --json

Use --json when another tool will parse the result. Human-readable output is for quick terminal checks.

Selectors

Most commands accept selectors instead of requiring long IDs:

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 and current resolve to the enclosing Orca-managed worktree from the shell's current directory or terminal context. Use explicit selectors in scripts that may run outside the target worktree.

Runtime commands

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

orca serve starts a runtime server in the foreground without opening the desktop window. Use it for remote or headless environments, and stop it with Ctrl-C.

Repos

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

Set the repo base ref before creating lots of worktrees so new tasks branch from the right place by default.

Worktrees

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

When worktree create runs from inside an Orca-managed worktree, Orca records the new worktree as a child when it can infer the relationship. Pass --parent-worktree active to be explicit, or --no-parent when the new work is independent.

Agent startup flags:

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 launches the selected agent in the first terminal. --prompt sends initial work to that agent. --setup run|skip|inherit controls repo setup hooks; inherit follows the repo policy.

Terminals

orca terminal list --worktree active --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 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

Omit --terminal to target the active terminal in the current worktree. Read before sending when you are not sure what the terminal is waiting for.

For long output, use cursor reads. Save nextCursor from one read, then pass it back with --cursor to fetch only new output.

Files

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

Paths are relative to the selected worktree. open-changed reads git status and opens changed files in edit, diff, or both modes.

Built-in browser

Browser commands control Orca's embedded browser tab for the selected worktree. They do not control Chrome, Safari, or the Orca desktop UI.

Use a snapshot -> act -> snapshot loop:

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 "[email protected]" --worktree active --json
orca wait --text "Welcome" --worktree active --json
orca screenshot --worktree active --json

Refs such as @e3 come from snapshot. Re-snapshot after navigation, tab switches, clicks that change the page, and any stale-ref error.

Tab and capture commands:

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

Use orca exec --command "<agent-browser command>" --json only for browser actions that do not have a typed Orca command yet.

Browser device emulation:

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

Desktop computer use

Use orca computer for native desktop apps outside the built-in browser:

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

See Computer use for the full workflow and permission setup.

Mobile emulator

The mobile emulator commands control iOS Simulator devices through Orca's worktree-scoped bridge. Use them instead of raw serve-sim or simctl when an agent is operating from inside Orca, so lifecycle and active-device state stay attached to the current worktree.

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

Coordinates are normalized from 0 to 1. Prefer tap for single taps, and use gesture for drags or multi-step touch input. Pass --device <udid-or-name> or --emulator <id> when a script must target a specific simulator instead of the worktree's active emulator.

Automations, environments, and hooks

Scheduled prompts:

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

Remote runtime environments:

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

Agent status hooks:

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

Agent habits

Prefer --json for automation and agent calls.
Prefer selectors over parsing UI labels.
Read terminal state before sending input unless the next input is obvious.
Use worktree comments for progress checkpoints. See Worktree checkpoints.
Use Orchestration for tracked multi-agent dispatches instead of ad hoc terminal prompts.