orca-cli

# Orca CLI

Use `orca` when Orca's running editor/runtime is the source of truth. On Linux, use `orca-ide` wherever this file says `orca`.

**Dev builds (`pnpm dev`):** after `pnpm build:cli`, the dev CLI is exposed as `orca-dev` (the global shim points at this checkout's wrapper + out/cli). Inside a dev Orca's terminals use `orca-dev emulator ...` (or `./config/scripts/orca-dev.mjs emulator ...` for worktree-local invocation that does not depend on the /usr/local/bin symlink). Plain `orca` targets any installed production Orca. The app's own agent preambles use `orca-dev` automatically in dev mode.

Use plain shell tools when Orca state does not matter.

## Start Here

```bash
command -v orca || command -v orca-ide
orca status --json
orca worktree ps --json
orca terminal list --json
```

If Orca is not running, start it:

```bash
orca open --json
orca status --json
```

Prefer `--json` for agent-driven calls. If the CLI is missing, say so explicitly instead of inspecting source files first.

## Worktrees

An Orca worktree is Orca's tracked view of a repo checkout, its metadata, terminals, browser tabs, and UI state.

Common commands:

```bash
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
orca worktree list --repo id:<repoId> --json
orca worktree ps --json
orca worktree current --json
orca worktree show --worktree <selector> --json
orca worktree create --repo id:<repoId> --name related-task --json
orca worktree create --repo id:<repoId> --name related-task --parent-worktree active --json
orca worktree create --repo id:<repoId> --name folder-child --parent-worktree folder:<folderId> --json
orca worktree create --name child-task --agent codex --prompt "hi" --json
orca worktree create --name independent-task --no-parent --json
orca worktree set --worktree id:<worktreeId> --display-name "My Task" --json
orca worktree set --worktree active --comment "reproduced bug; testing fix" --json
orca worktree set --worktree active --workspace-status in-review --json
orca worktree rm --worktree id:<worktreeId> --force --json
```

Selectors:

- `id:<worktreeId>`, `name:<displayName>`, `path:<absolutePath>`, `branch:<branchName>`, `issue:<number>`
- `active` / `current` for the enclosing Orca-managed worktree from the shell cwd
- For `worktree create --parent-worktree` only, folder/worktree parent context keys are also valid: `folder:<folderId>`, `worktree:<worktreeId>`, `id:folder:<folderId>`, `id:worktree:<worktreeId>`

Lineage rules:

- When creating from inside an Orca-managed worktree or folder context, Orca infers the current parent context when it can.
- Use `--parent-worktree active` when the child worktree relationship should be explicit.
- Use `--parent-worktree folder:<folderId>` or `--parent-worktree worktree:<worktreeId>` when a folder or worktree parent context should be explicit.
- Use `--no-parent` only when the new work is independent.
- `--no-parent` only controls Orca lineage; it does not choose the Git base. For independent top-level work, omit `--base-branch` so Orca uses the repo default base, or explicitly pass the repo default base. Never base it on the current feature branch unless the user asks for stacked work or "branch from current".
- If `--repo` is omitted, Orca infers the repo from the current Orca worktree when possible.

Agent/setup flags:

```bash
orca worktree create --name task --agent codex --prompt "hi" --json
orca worktree create --name task --agent claude --setup run --json
orca worktree create --name task --setup skip --json
orca worktree create --name task --run-hooks --json
```

- `--agent <id>` launches that agent in the first terminal; `--prompt <text>` sends initial work to it.
- `--setup run|skip|inherit` controls repo setup hooks. Default is `inherit`, which follows the repo's setup policy.
- `--run-hooks` is a legacy alias for `--setup run`; it also reveals/activates the new worktree.
- `--agent`, `--activate`, and `--run-hooks` reveal the new worktree. Plain create stays in the background.
- Let Orca choose setup terminal placement from repo settings, including tab vs split behavior. Do not manually create extra setup terminals.
- If an older installed CLI rejects `--agent`, `--prompt`, or `--setup`, create the worktree normally, then run `orca terminal create --worktree <selector> --command "codex"` and `orca terminal send` if a prompt is needed.
- `worktree create` creates a new checkout. For a fresh agent in the current checkout, use `orca terminal create --worktree active --command "codex" --json`.

## Worktree Comments

A worktree comment is the short status text shown in Orca's workspace list/card for quick progress visibility.

Coding agents should update the active worktree comment at meaningful checkpoints:

```bash
orca worktree set --worktree active --comment "fix implemented; running integration tests" --json
```

Update after meaningful state changes such as repro, fix, validation, handoff, or blocker. Keep comments short/current; failures are best-effort unless Orca state was requested.

Card status uses `--workspace-status <id>`; defaults are `todo`, `in-progress`, `in-review`, `completed`.

## Terminals

Common commands:

```bash
orca terminal list --worktree id:<worktreeId> --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 read --json
orca terminal send --terminal <handle> --text "continue" --enter --json
orca terminal send --text "echo hello" --enter --json
orca terminal wait --terminal <handle> --for exit --timeout-ms 5000 --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
orca terminal stop --worktree id:<worktreeId> --json
orca terminal create --json
orca terminal creat