# CLI core reference

> Flags and signatures for `open`, `serve`, `status`, `repo`, `worktree`, `terminal`, `file`, `environment`, and `agent hooks` command groups.

- Repository: stablyai/orca
- GitHub: https://github.com/stablyai/orca
- Human docs: https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c
- Complete Markdown: https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/llms-full.txt

## Source Files

- `src/cli/specs/core.ts`
- `src/cli/specs/file.ts`
- `src/cli/specs/environment.ts`
- `src/cli/specs/agent-hooks.ts`
- `src/cli/args.ts`
- `src/cli/help.ts`
- `src/cli/handlers/core.ts`

---

---
title: "CLI core reference"
description: "Flags and signatures for `open`, `serve`, `status`, `repo`, `worktree`, `terminal`, `file`, `environment`, and `agent hooks` command groups."
---

The `orca` binary routes argv through `src/cli/args.ts` (parse, validate, positional normalization), matches a `CommandSpec` from `src/cli/specs/*.ts`, and dispatches handlers that call the local runtime socket or a paired remote runtime over WebSocket. Command usage strings, allowed flags, and per-command notes are the source of truth in those spec files; handlers in `src/cli/handlers/` enforce extra constraints (remote cwd, selector resolution, exit codes).

## Global flags and runtime targeting

These flags are allowed on every command in the groups below (`GLOBAL_FLAGS` in `src/cli/args.ts`):

| Flag | Role |
| --- | --- |
| `--help` | Print command or group help (`orca help <path>` also works). |
| `--json` | Emit machine-readable JSON (`ok`, `result`, `_meta`; failures use RPC error shape). |
| `--pairing-code <code>` | Target a remote runtime via `orca://pair#...` (or bare payload). |
| `--environment <selector>` | Target a saved environment by id or name. |

<ParamField body="pairing-code" type="string">
Mutually exclusive with `--environment`. Same constraint applies to `ORCA_PAIRING_CODE` / `ORCA_REMOTE_PAIRING` vs `ORCA_ENVIRONMENT`.
</ParamField>

<Warning>
`environment`, `serve`, and `agent` commands ignore `--pairing-code` and `--environment` (and suppress env-var fallback) so they always run against local user data.
</Warning>

Flag parsing accepts `--flag=value` so values can start with `--` (e.g. `--text=--help`). Unknown commands or flags fail with `invalid_argument` before any runtime connection attempt.

## Startup commands

### `orca open`

Launches the Orca app when needed and polls until the runtime is reachable (default 15s). Returns the same readiness shape as `status`.

```bash
orca open [--json]
```

### `orca serve`

Starts a **headless** Orca runtime in the foreground (no desktop window). Prints the runtime endpoint; stop with Ctrl+C. Forwards signals to the child process.

```bash
orca serve [--port <port>] [--pairing-address <host>] [--mobile-pairing] [--no-pairing] [--json]
```

| Flag | Notes |
| --- | --- |
| `--port` | Integer 0–65535; passed as `--serve-port` to the app executable. |
| `--pairing-address` | Address clients should use (LAN, Tailscale, SSH forward, tunnel). |
| `--mobile-pairing` | Mobile-scoped pairing QR/link instead of default runtime-environment pairing. |
| `--no-pairing` | Disables pairing output; **cannot** be combined with `--mobile-pairing`. |

With `--json`, the child receives `--serve-json`. When a web client bundle is available, the server may also print a browser URL with embedded pairing data.

### `orca status`

Reports app process, runtime reachability, runtime id, and graph state. Sets exit code **1** when the runtime is not reachable (human and JSON modes).

```bash
orca status [--json]
```

Human text fields include `appRunning`, `pid`, `runtimeState`, `runtimeReachable`, `runtimeId`, `graphState`. On a paired remote runtime, `app.running` is reported as true with `pid: null`.

```text
argv → parseArgs / validateCommandAndFlags
         → RuntimeClient (local metadata socket | WebSocket if paired)
         → handler → RPC method → printResult / reportCliError
```

## Environment commands

Saved environments are stored under the CLI user-data path and managed **locally** (no runtime RPC). `environment add` requires `--pairing-code` on the command line (also a global flag elsewhere).

| Command | Usage |
| --- | --- |
| `environment add` | `orca environment add --name <name> --pairing-code <code> [--json]` |
| `environment list` | `orca environment list [--json]` |
| `environment show` | `orca environment show --environment <selector> [--json]` |
| `environment rm` | `orca environment rm --environment <selector> [--json]` |

Successful saves are redacted for display (pairing secrets are not echoed). `environment show` / `rm` resolve `<selector>` by environment id or name.

## Repo commands

All repo commands call runtime RPC methods (`repo.list`, `repo.add`, `repo.show`, `repo.setBaseRef`, `repo.searchRefs`).

| Command | Usage | Required flags |
| --- | --- | --- |
| `repo list` | `orca repo list [--json]` | — |
| `repo add` | `orca repo add --path <path> [--json]` | `--path` |
| `repo show` | `orca repo show --repo <selector> [--json]` | `--repo` |
| `repo set-base-ref` | `orca repo set-base-ref --repo <selector> --ref <ref> [--json]` | `--repo`, `--ref` |
| `repo search-refs` | `orca repo search-refs --repo <selector> --query <text> [--limit <n>] [--json]` | `--repo`, `--query` |

<Note>
On a **remote** runtime, `repo add --path` must be an **absolute path on the server**. Relative paths are rejected because the CLI cwd is on the client machine.
</Note>

Repo selectors: `id:<id>`, `name:<name>`, `path:<path>`.

## Worktree commands

| Command | Usage | Notable flags |
| --- | --- | --- |
| `worktree list` | `orca worktree list [--repo <selector>] [--limit <n>] [--json]` | Filter by repo |
| `worktree show` | `orca worktree show --worktree <selector> [--json]` | — |
| `worktree current` | `orca worktree current [--json]` | Resolves enclosing worktree from **local** cwd → `id:<id>` |
| `worktree create` | See below | Parent lineage, hooks, activation |
| `worktree set` | `orca worktree set --worktree <selector> [--display-name <name>] [--issue <n>] [--comment <text>] [--parent-worktree <selector>] [--no-parent] [--json]` | Pass `--issue` with no value to clear |
| `worktree rm` | `orca worktree rm --worktree <selector> [--force] [--run-hooks] [--json]` | Archive hooks skipped unless `--run-hooks` |
| `worktree ps` | `orca worktree ps [--limit <n>] [--json]` | Orchestration-oriented summary |

### `worktree create`

```bash
orca worktree create --repo <selector> --name <name> \
  [--base-branch <ref>] [--issue <number>] [--comment <text>] \
  [--parent-worktree <selector>] [--no-parent] [--run-hooks] [--activate] [--json]
```

| Flag | Behavior |
| --- | --- |
| (default parent) | Infers parent from `ORCA_TERMINAL_HANDLE`, else cwd-enclosing worktree, unless `--no-parent` or explicit `--parent-worktree`. |
| `--parent-worktree` | Explicit parent; value `active` resolves like `worktree current`. |
| `--no-parent` | Independent worktree; mutually exclusive with `--parent-worktree`. |
| `--run-hooks` | Forces repo setup hooks per repository policy; also sets `activate` so hooks can run in the first terminal. |
| `--activate` | Reveals the new worktree in the app (also implied by `--run-hooks`). |

Non-JSON create may print `warning:` lines for hook failures and a `parent:` lineage summary on stderr.

Worktree selectors: `id:<id>`, `branch:<branch>`, `issue:<number>`, `path:<path>`, `active`, `current`. On remote runtimes, `active` / `current` are **invalid**—use an explicit server-side selector.

## Terminal commands

Terminal handles come from `orca terminal list --json` (`term_…`). When `--terminal` is omitted, the CLI resolves the **active** terminal in the current (or selected) worktree via `terminal.resolveActive`.

| Command | Usage |
| --- | --- |
| `terminal list` | `orca terminal list [--worktree <selector>] [--limit <n>] [--json]` |
| `terminal show` | `orca terminal show [--terminal <handle>] [--json]` |
| `terminal read` | `orca terminal read [--terminal <handle>] [--cursor <n>] [--limit <n>] [--json]` |
| `terminal send` | `orca terminal send [--terminal <handle>] [--text <text>] [--enter] [--interrupt] [--json]` |
| `terminal wait` | `orca terminal wait [--terminal <handle>] --for exit\|tui-idle [--timeout-ms <ms>] [--json]` |
| `terminal stop` | `orca terminal stop --worktree <selector> [--json]` |
| `terminal create` | `orca terminal create [--worktree <selector>] [--title <name>] [--command <text>] [--focus] [--json]` |
| `terminal rename` | `orca terminal rename [--terminal <handle>] [--title <text>] [--json]` |
| `terminal split` | `orca terminal split [--terminal <handle>] [--direction horizontal\|vertical] [--command <text>] [--json]` |
| `terminal switch` | `orca terminal switch [--terminal <handle>] [--json]` |
| `terminal focus` | Alias for `terminal switch` |
| `terminal close` | `orca terminal close [--terminal <handle>] [--json]` |

### `terminal read` cursors

`--cursor` must be a non-negative integer (from a prior read’s `nextCursor`). Use incremental reads to capture agent output: read before `send`, then `read --cursor <prev>` after `wait`.

### `terminal wait`

| `--for` value | Meaning |
| --- | --- |
| `exit` | Wait until the terminal process exits. |
| `tui-idle` | Wait until the TUI reports idle (agent UIs). |

Client RPC timeout is at least `timeout-ms + 5000` (cap 5 minutes default when unset). Exit code **1** when `satisfied` is false (including blocked waits).

<Warning>
Remote `terminal create` requires `--worktree` because client cwd cannot identify a server worktree.
</Warning>

Local interactive agent commands may use a renderer-backed terminal path when classified as such; `--focus` controls UI activation.

## File commands

Paths are **relative to the selected worktree**. Positional path is supported: `orca file open <path>` (normalized to `--path`).

| Command | Usage |
| --- | --- |
| `file open` | `orca file open <path> [--worktree <selector>] [--json]` |
| `file diff` | `orca file diff <path> [--staged] [--worktree <selector>] [--json]` |
| `file open-changed` | `orca file open-changed [--mode edit\|diff\|both] [--worktree <selector>] [--json]` |

| Flag | Behavior |
| --- | --- |
| `--staged` | (`file diff`) Open staged SCM diff instead of unstaged. |
| `--mode` | (`open-changed`) Default `diff`. `edit` skips deleted paths; `both` opens edit and diff targets. |

Worktree selection: explicit `--worktree`, else local cwd resolution; remote commands **require** `--worktree`. Changed files come from `git.status` for the worktree.

## Agent hooks commands

Controls Orca-managed agent status hooks (install state in persisted settings and managed hook files).

| Command | Usage |
| --- | --- |
| `agent hooks status` | `orca agent hooks status [--json]` |
| `agent hooks on` | `orca agent hooks on [--json]` |
| `agent hooks off` | `orca agent hooks off [--json]` |

`on` / `off` prefer updating a **reachable** runtime via `settings.update`; otherwise they patch `orca-data.json` offline (`appliedBy: runtime` vs `offline`). JSON/human output includes `agentStatusHooksEnabled`, `settingsPath`, `appliedBy`, and per-agent install `statuses`.

## JSON output and exit codes

<RequestExample>

```bash
orca worktree current --json
```

</RequestExample>

<ResponseExample>

```json
{
  "id": "rpc-…",
  "ok": true,
  "result": { "worktree": { "id": "…", "branch": "…", "path": "…" } },
  "_meta": { "runtimeId": "…" }
}
```

</ResponseExample>

Failures with `--json`: RPC failures print the server error object; local CLI errors use `{ "ok": false, "error": { "code", "message" }, "_meta": { "runtimeId": null } }`. Common codes include `invalid_argument`, `runtime_unavailable`, `selector_not_found`, `selector_ambiguous`, `runtime_open_timeout`, `incompatible_runtime`.

| Situation | Exit code |
| --- | --- |
| `status` with unreachable runtime | 1 |
| `terminal wait` with `satisfied: false` | 1 |
| Any caught CLI error | 1 (default) |
| `serve` child exit code | Propagated to `process.exitCode` |

## Help discovery

```bash
orca                          # root help
orca help worktree create     # command help
orca worktree create --help   # same
orca worktree                 # group listing
```

Per-flag descriptions are generated in `src/cli/help.ts` (`formatFlagHelp`).

## Related pages

<CardGroup>
  <Card title="Selectors and JSON output" href="/selectors-json-output">
    Selector grammar, global flags, JSON errors, and remote resolution rules in depth.
  </Card>
  <Card title="CLI scripting workflow" href="/cli-scripting-workflow">
    End-to-end automation patterns with open, status, terminals, and worktree comments.
  </Card>
  <Card title="Runtime environments" href="/runtime-environments">
    Headless serve, pairing codes, and targeting remote runtimes.
  </Card>
  <Card title="Terminals and agents" href="/terminals-and-agents">
    PTY lifecycle, agent detection, and when to use terminal CLI vs orchestration.
  </Card>
  <Card title="Repository hooks" href="/repository-hooks">
    `orca.yaml` setup/archive hooks and `--run-hooks` on create/remove.
  </Card>
</CardGroup>