CLI reference

The orca CLI connects to the daemon and provides quick access to common operations. It's also used by spawned reasoning agents (Pilot, Overseer) to submit plans and answer decisions.

Installation

npm install -g orcasynth   # makes `orca` available globally
# or, from a source checkout:
node dist/cli/index.js <command>

Two command families

• API commands (ls, ready, sessions, close, plan, overseer, api) talk to the daemon REST API. They auto-start the daemon if it isn't running (disable with ORCA_AUTOSTART=0).
• Lifecycle commands (up, down, status, update, install) manage the daemon itself — they never auto-start it. Run orca with no argument for the interactive launcher menu.

Environment variables

Commands

orca ls

List all tasks from the daemon. Calls GET /tasks.

orca ls

[
  {
    "id": "orca-ab12cd34",
    "title": "Fix login page",
    "status": "open",
    "priority": "P2",
    "labels": ["exec:sonnet"]
  }
]

orca ready

List tasks that are ready to be worked on (open, non-epic, all dependencies fulfilled). Calls GET /tasks/ready.

orca ready

orca sessions

List active orca-managed tmux sessions (orca-* prefix). Calls GET /sessions.

[
  { "name": "orca-SwiftLake0", "role": "agent", "agent": "SwiftLake0" },
  { "name": "orca-pilot-Aria", "role": "pilot", "agent": "Aria" },
  { "name": "orca-overseer-m-my-project-a1b2c3d4", "role": "overseer", "agent": "", "missionId": "m-my-project-a1b2c3d4" }
]

orca close

Close a task with a result summary and outcome. Used by agents to signal completion. Calls PATCH /tasks/:id with status: "closed", result_summary, and outcome.

orca close orca-ab12cd34 --summary "Fixed the login redirect bug" --outcome ok
orca close orca-ef56gh78 --summary "Could not reproduce the issue" --outcome fail

orca plan submit

Used by the Pilot agent to submit a structured plan for an async planning job. The job ID is injected via ORCA_PLAN_JOB — the Pilot never passes it manually. Calls POST /plan/:jobId/submit.

orca plan submit --phases '{"title":"Set up database","type":"chore"},{"title":"Create API endpoints","type":"feature"}'

orca overseer poll

Used by the parked Overseer agent to long-poll for pending decisions. The CLI loop absorbs heartbeat responses (sent every ~25s to keep the HTTP connection alive) so the LLM is woken only for real decisions. Requires ORCA_MISSION to be set.

orca overseer poll

{
  "id": "a1b2c3d4e5f6",
  "kind": "task",
  "context": {
    "title": "Set up database schema",
    "labels": ["exec:sonnet", "agent:Atlas0"]
  }
}

Blocks indefinitely, surfacing only decisions with an id or error field. The loop ends when the daemon kills the session (mission disengaged) or an error arrives.

orca overseer decide

Used by the parked Overseer agent to submit a verdict. Calls POST /missions/:missionId/overseer/decide. A question-kind decision uses --choice; a permission/review decision uses --approve or --escalate.

orca overseer decide --id a1b2c3d4e5f6 --approve --confidence 0.85 --rationale "Schema change is scoped and safe"
orca overseer decide --id b2c3d4e5f6 --escalate --rationale "This migrates production data — needs human review"
orca overseer decide --id c3d4e5f6a1b2 --choice opt_rollback --rationale "Rollback is the safest option"

orca api — generic REST passthrough

Call any Orca endpoint with no per-endpoint CLI command. Reads ORCA_URL/ORCA_TOKEN from the environment the daemon injects into every spawned agent, so an agent (including the assistant) can drive any endpoint. The forward logic lives in the shared callOrcaApi core (src/shared/apiClient.ts) — exactly the same path the MCP tools use.

orca api GET /tasks
orca api POST /tasks '{"title":"Fix the build","project_id":1}'
orca api POST /tasks/plan '{"goal":"Add dark mode","project_id":1}'
orca api GET /sessions

Response — the parsed JSON response body (pretty-printed), or the raw text when the body isn't JSON.

Lifecycle commands

These manage the daemon itself and never auto-start it.

orca up

Starts the daemon (:4400) and the web UI (:4500) in the background. Fails loudly with orca daemon did not become healthy if the daemon never becomes healthy.

orca down

Stops the daemon and the web UI.

orca status

Prints a one-glance block showing which services are running and healthy:

  orcasynth v1.4.41

  daemon  ●  running  :4400  healthy
  web     ●  running  :4500  healthy  http://localhost:4500

orca update

Updates to the latest npm release and restarts the services in place. Self-locating and systemd-aware.

sudo npm install -g orcasynth@latest --prefix <install-prefix> && \
  sudo systemctl restart orca-daemon orca-web

orca install

Guided provisioning wizard (run as root): systemd units, a reverse proxy, and the first admin. Supports unattended mode (orca install --unattended) — choose domain/IP:port/localhost, TLS (Let's Encrypt where applicable), and the autopilot engine. See orca install --help for flags.

Daemon autostart

The CLI automatically starts the daemon if it isn't running:

1. Hits GET /health.
2. If unreachable, spawns node dist/daemon/index.js as a detached child process.
3. Polls the health endpoint up to 50 times (100ms interval) until ready.
4. Times out with orca daemon did not become healthy if the daemon fails to start.

ORCA_AUTOSTART=0 orca ls   # disable autostart for one invocation

Exit codes

Adding commands

New daemon-backed commands are added in src/cli/index.ts by adding a case to the switch in run(), plus the corresponding method in src/cli/client.ts. Add the command name to the API_COMMANDS set so the daemon auto-starts for it. Lifecycle commands go through runLifecycle() in src/cli/commands.ts instead.

For a generic one-off, orca api <METHOD> <path> [body] reaches any endpoint with no CLI edit.

Up next: Architecture — modules, timer loops, and the request/spawn flow.

© 2026 ORCA · MIT Licensed · View source on GitHub