Orca CLI Reference

Add a terminal script to the desktop app on this machine. The desktop app must have been launched once so its local database exists, and the CLI must have an active organization so the script is imported into the correct v2 profile. When iterating on one script, pass --upsert so each revision replaces the last instead of piling up copies in the Scripts bar.

orca scripts add --name dev --command "bun run dev"
orca presets add --name services \
  --command "docker compose up" --command "bun run dev" \
  --execution-mode split-pane
orca scripts add --name "Open in GitHub" --command "gh pr view --web" --upsert

List the terminal scripts on this machine with the id each other command takes. status is importing or deleting while a change is waiting for the desktop app to open or refocus with the same organization active. Scripts created in the desktop app's Settings are stored in the app profile only and do not appear here.

orca scripts list
orca scripts list --json

Change fields on an existing script. Unspecified fields keep their values, and the desktop app updates its copy in place, so the script keeps its position in the Scripts bar. Edits made in the desktop app's Settings do not flow back to the CLI: an edit here replaces the app's copy with what orca scripts list shows plus your changes.

orca scripts edit <id> --command "gh pr view --web"
orca scripts edit <id> --name "Open PR" --hidden
orca scripts edit <id> --all-projects --no-hidden

Delete a script. The desktop app removes its copy the next time it opens or refocuses with the same organization active (immediately when it is running); until then the script lists with status deleting.

orca scripts delete <id>

Authenticate via browser OAuth and store a session token at ~/.orca/config.json.

Single-org accounts are selected automatically. With multiple orgs and a TTY, the CLI prompts; with multiple orgs and no TTY, you must pass --organization or the command exits 1 listing the available slugs.

orca auth login
orca auth login --organization acme

To sign in with an API key (useful for CI or any environment where the OAuth browser flow isn't an option), pass --api-key. The CLI validates the key, stores it at ~/.orca/config.json, and clears any prior OAuth session.

orca auth login --api-key sk_live_…
orca auth login --api-key sk_live_… --organization acme

◇  Authorized!
│  Satya Patel (you@example.com)
│  Organization: Acme
└  Logged in successfully.

{
  userId: string;
  organizationId: string;
  organizationName: string;
}

Clear stored credentials: both an OAuth session and a stored API key. Does not call the API and does not clear the active organization (your preferred org persists across re-logins).

orca auth logout

Logged out.

{ message: "Logged out." }

Show the current user, active organization, and auth source.

orca auth whoami

Signed in as Satya Patel (you@example.com)
Organization: Acme
Auth: Session (expires in 32 min)

{
  userId: string;
  email: string;
  name: string;
  organizationId: string;
  organizationName: string;
  authSource: "override" | "config" | "oauth";
}

If a manifest exists and the PID is alive, returns the existing instance's { pid, endpoint }. Otherwise spawns the host server binary, polls /trpc/health.check for up to 10 seconds, and writes the manifest. Binds to 127.0.0.1 only.

orca start --daemon

// Freshly started
{
  pid: number;
  port: number;
  organizationId: string;
}

// Already running
{
  pid: number;
  endpoint: string;
}

Sends SIGTERM, waits up to 10 seconds, sends SIGKILL if still alive, then removes the manifest. If sending SIGTERM itself throws, the command errors and the manifest is left in place.

orca stop

// No manifest
{ running: false }

// Manifest existed
{ pid: number; organizationId: string }

healthy reflects a live health.check request (2-second timeout).

orca status

// No manifest
{ running: false; organizationId: string; hostId: string }

// Manifest exists but PID is dead
{
  running: false;
  stale: true;
  pid: number;
  organizationId: string;
  hostId: string;
}

// Running
{
  running: true;
  healthy: boolean;
  pid: number;
  port: number;
  endpoint: string;
  organizationId: string;
  hostId: string;
  hostName: string;
  uptimeSec: number;
}

Downloads the matching orca-<platform>.tar.gz from GitHub Releases and atomically replaces the install root. Only available in built binaries; running from bun run dev errors out.

orca update                     # upgrade to the latest release
orca update --check             # show current → target without installing
orca update --version 0.1.2     # install a specific version (up or down)

Updated 0.1.4 → 0.1.5 (/Users/you/.local/share/orca)

// --check
{
  current: string;
  target: string;
  upToDate: boolean;
  pinned: boolean;
}

// install
{
  current: string;
  target: string;
  updated: boolean;
  installRoot?: string;
}

List organizations available to the current auth context. Marks the active one.

Set the active organization in ~/.orca/config.json.

orca organization switch acme
orca org switch org_…

List members in the active organization.

orca organization members list
orca org members list -s satya

List projects on a host. Defaults to this machine; pass --host <id> for another host.

Create a fresh project on a host. Two modes:

• Clone: pass --clone <url> and --parent-dir. The host clones the repo into <parent-dir>/<derived-name>/.
• Import: pass --import <path> to register a repo that already exists on disk.

Either way, the project is registered on the host with no workspaces yet; create one with orca ws create --project <id> --name local --checkout local --local (the repo's checkout as it is) or --branch <name> (its own worktree).

create always creates a new cloud project, even if your org already has one for the same Git URL. Use projects setup when adopting an existing project on a fresh machine.

orca projects create --name "my-app" --local --clone https://github.com/org/my-app.git --parent-dir ~/code
orca projects create --name "my-app" --local --import ~/code/my-app

Adopt an existing project onto a host without creating a duplicate cloud record. Counterpart to create for the "new machine, repo already in the org" case.

Find the project ID via projects list.

Idempotent: re-running against a project that's already set up at the same path is a no-op.

# Pick an ID from `orca projects list`, then clone it onto this machine
orca projects setup 47c31b04-… --local --parent-dir ~/code

# Or register an existing local checkout
orca projects setup 47c31b04-… --local --import ~/code/my-app

List hosts registered to the active organization. Host registration happens via orca start on each machine. There is no separate registration command.

orca hosts list

Set (or clear) the command used to wake a host.

orca hosts set-wake my-sandbox vercel sandbox resume my-box
orca hosts set-wake my-sandbox --clear

Wake a host by running its configured wake command locally, streaming its output.

orca hosts wake my-sandbox

List workspaces on a host. Defaults to this machine; pass --host <id> for another host. Workspaces are host-owned; there is no org-wide listing (the desktop app is the cross-host view). projectName falls back to the raw project id when the host doesn't know the project's name.

Create a workspace on the target host. With --project, specify one of --checkout local, --branch, --pr, or --task (--branch and --pr are mutually exclusive). If you pass --agent, you must also pass --prompt. --command runs a one-off shell command in the workspace directory and is independent of --agent/--prompt. Pass either or both. --model and --effort require --agent; see the agent effort levels below.

--checkout local shares the project's existing files, git index and checked-out branch. It does not switch branches or run setup. Do not combine it with --branch, --pr, --base-branch, or --skip-branch-prefix. Local creation requires a host that supports local workspaces; older hosts reject it without creating a worktree. --local selects this machine and is independent of --checkout local.

Pass --session explicitly to create a session: a project-less workspace backed by a managed folder under ~/.orca/sessions, initialized as its own git repo. Sessions have no branch semantics, so --branch, --pr, --task, --base-branch, --checkout, --skip-branch-prefix, and --tag are rejected, --name is optional, and the output has no alreadyExists field. Host workspace creation requires either --project <id> or --session; omitting both is an error.

orca workspaces create \
  --project prj_… \
  --name "fix-login-bug" \
  --branch fix/login-bug \
  --local

orca workspaces create \
  --project prj_… \
  --name "review-pr-123" \
  --pr 123 \
  --local

# Project-less session with an agent
orca workspaces create --session --local --agent claude --prompt "…"

# Tags group the workspace into sidebar folders — no folder setup needed
orca workspaces create --project prj_… --name "perf-spike" --branch perf/spike --local --tag perf

Delete one or more workspaces on the target host (default: this machine).

orca workspaces delete ws_a ws_b ws_c

Show details for a single workspace on its host. --field is handy in scripts: orca workspaces get --field worktreePath.

orca workspaces get ws_…
orca workspaces get --field branch   # inside a workspace

Update a workspace on its host (default: this machine). --tag replaces the whole tag set — tagging is how workspaces group into sidebar folders, so retagging moves the workspace between folders.

orca workspaces update ws_… --name "better-name"
orca workspaces update ws_… --task-id tsk_…
orca workspaces update ws_… --tag perf --tag infra
orca workspaces update ws_… --clear-task

Open a workspace in the Orca desktop app.

orca workspaces open ws_…
orca workspaces open ws_… --print

List agents configured on a host. First call on a fresh host seeds the bundled defaults.

orca agents list --local
orca agents list --host host_…

Create an agent session in an existing workspace on its host (default: this machine): starts the named preset (or HostAgentConfig instance) in a fresh terminal session there.

orca agents create --workspace ws_… --agent claude --model sonnet --effort high --prompt "Audit the login flow"
orca agents create --workspace ws_… --agent codex --prompt "Review this diff" --attachment ./trace.log
# Restore a killed agent session by the agent's own session id
orca agents create --workspace ws_… --agent claude --resume-session 0b7c…

Agent models

Model is an explicit override for one launch. If you omit --model, Orca passes no model flag and the agent uses its own configured default. Ids match the desktop model picker: Claude takes a family alias (fable, opus, sonnet, haiku) that tracks the newest release, or a pinned id such as claude-opus-4-8. The host rejects an unknown id before launching the agent, and the error names every id that agent accepts. Agents without a model picker, including Orca chat, reject an explicit model override.

Agent effort levels

Effort is an explicit override for one launch. If you omit --effort, Orca passes no effort flag and the agent uses its own configured default. The host rejects unsupported values before launching the agent.

Other agents, including Orca chat, currently use their own default and reject an explicit effort override.

Create a terminal session in an existing workspace on its host (default: this machine): opens a fresh PTY in the worktree, optionally running a command.

orca terminals create --workspace ws_… --command "bun install && bun test"
orca terminals create --workspace ws_…

List the live terminal sessions in a workspace. Presence in the list means the PTY exists, not that an agent inside it is working or idle.

Read a terminal's current screen back as text without mutating the session.

orca terminals read --workspace ws_… --terminal term_… --max-lines 240

Send a follow-up message to a terminal already running in a workspace, e.g. to give an agent new instructions mid-session.

Close (dispose) a terminal running in a workspace. This ends the session.

List the browser panes open in a workspace.

Open a URL in a browser pane and return its paneId. Requires the workspace to be visible in the desktop app (the renderer creates the pane).

orca browser open --workspace ws_… --url http://localhost:3000 --target new-tab

Point an existing pane at a new URL. file://, chrome://, and custom schemes are refused.

Capture a PNG screenshot of the pane's page.

Evaluate JavaScript in the page and return the result — the ergonomic path for reading or nudging the DOM.

orca browser eval --workspace ws_… --pane pane_… \
  --code "document.querySelector('h1')?.textContent"

Read the pane's captured console output.

Print a raw Chrome DevTools Protocol WebSocket endpoint for the pane, for browser-use / Playwright-class tools (mouse, keyboard, scroll, DOM, network). The URL embeds an auth token — treat it as a secret.

List tasks in the active organization.

orca tasks list --assignee-me
orca t list -s "auth" --json

Get a task by ID or slug.

orca tasks get tsk_…
orca tasks get fix-login-bug

Create a task.

orca tasks create --title "Audit auth flow" --priority high

Update a task. Same fields as create, all optional.

orca tasks update fix-login-bug --priority urgent

Delete one or more tasks.

orca tasks delete tsk_a tsk_b

List task statuses in the active organization. Use the returned IDs with tasks list --status, tasks create --status-id, or tasks update --status-id.

orca tasks statuses list

List automations in the active organization.

Get an automation's metadata. The prompt body is omitted. Use automations prompt get to read it. Use automations logs for run history.

Create an automation. Automations are a Pro feature: create, run, and resume need a Pro or Enterprise subscription on the active organization and fail with Automations require the Pro plan. otherwise. Provide --prompt or --prompt-file; if both are present, the inline --prompt value is used. A --project or --workspace must exist on the target host; the CLI verifies this before creating the automation. Omit both for session mode: each run creates a project-less session workspace on the target host.

Every run's created workspace carries the automation's tags, which group it into the matching sidebar folders. By default automations are tagged automation, so their runs collect in an automation folder per project; pass --tag to file runs elsewhere.

orca automations create \
  --name "Weekday triage" \
  --project prj_… \
  --workspace ws_… \
  --rrule "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0" \
  --prompt-file ./prompts/triage.md

Update an automation's metadata (name, schedule, agent, host). All flags optional. Omitting a flag preserves the existing value: undefined means "no change", not "clear". Use automations prompt get or automations prompt set to read or replace the prompt body.

Print an automation's prompt body to stdout. The output is the raw prompt with no trailing newline added, so prompt get and prompt set round-trip byte-exactly.

# Read to a file
orca automations prompt get aut_… > prompt.md

# Verify a push landed
orca automations prompt get aut_… | diff - ./prompt.md

Replace an automation's prompt body. The new prompt fully overwrites the old one.

# Write from file
orca automations prompt set aut_… --from-file ./prompt.md

# Write from stdin
cat ./prompt.md | orca automations prompt set aut_… --from-file -

Delete an automation.

orca automations delete aut_…

Pause an automation (sets enabled: false).

orca automations pause aut_…

Resume an automation (sets enabled: true). The API recomputes nextRunAt on resume.

orca automations resume aut_…

Dispatch an automation immediately. Does not wait for completion.

orca automations run aut_…

List recent runs for an automation.

orca automations logs aut_…

List every settable key with its current value, default, and allowed values. isSet: false means the app is using its built-in default.

orca settings list

Print the effective value of one setting (falls back to the app default when unset).

orca settings get terminalFontSize

Set a setting. Booleans accept true/false/on/off/1/0/yes/no; enums and numeric ranges are validated the same way the desktop settings UI validates them.

orca settings set confirmOnQuit false
orca settings set terminalFontSize 16
orca settings set defaultEditor cursor
orca settings set selectedRingtoneId ping

Reset a setting to the app default.

orca settings reset terminalFontSize

List available themes: system (follows OS appearance), the built-ins (dark, light, monokai, catppuccin-latte, solarized-light, vellum), and any custom themes imported through the app.

orca settings theme list

Print the active theme.

orca settings theme get

Export a theme's full JSON definition, the starting point for creating a custom theme: export a built-in, edit the colors, then import it.

orca settings theme export dark --out my-theme.json

Import custom themes, using the same validation and normalization as the desktop's Appearance UI (ids are slugified; missing colors are filled from the built-in base theme; reserved ids like dark are rejected). Re-importing an id replaces that custom theme.

orca settings theme export dark --out my-theme.json
# edit my-theme.json (id, name, ui/terminal/editor colors)
orca settings theme import my-theme.json
orca settings theme set my-theme

Remove a custom theme. If it was the active theme (or a system light/dark mapping), that reference falls back to the default.

orca settings theme remove my-theme

Set the active theme and/or the system light/dark mappings. A running desktop app restyles live; without one the theme applies on next launch. (On app versions without live reload, quit the app first, then set, then relaunch, or the app may overwrite the change.)

orca settings theme set monokai
orca settings theme set system --system-light light --system-dark monokai