CLI reference

the global contracts every orcr command shares: the noun/verb surface, the --json envelope, confirmation, duration units, target grammar, and the exit-code table.

the orcr CLI has four nouns (agent, loop, server, api) plus two standalone verbs (orcr top and orcr scaffold). every server-touching verb maps 1:1 to a socket method (see the socket API reference); the CLI is one thin client of that protocol.

these pages mirror orcr <command> --help. parity between the docs, the skill, and live --help is enforced by tests/skill_docs.rs, so flags here do not drift from the binary.

the per-noun pages cover each verb, flag, and output shape:

orcr agent: spawn, message, await, read, and stop agents.
orcr loop: durable cron for any command, and its runs.
orcr server: operate the long-lived server.
orcr api: the protocol schema and a runtime snapshot.
orcr top: the live monitoring TUI (the one command with no --json).
orcr scaffold: set up a TypeScript workflow project locally.

the `--json` envelope

every command supports --json and prints exactly one envelope object on stdout. all logs go to stderr, so the stdout stream is always a single parseable JSON value.

{ "ok": true, "result": { } }

{ "ok": false, "error": { "code": "not_found", "message": "…", "details": { } } }

the result shapes are part of the API contract and are documented per verb; the full set of methods, params, and results is published by orcr api schema. verbs with no meaningful payload return {} or an obvious echo.

orcr top is the one exception: it is a TUI and has no --json. machine-readable live state comes from orcr api snapshot or orcr agent ls --json instead.

targets: `<path|uuid>` vs `<pattern|uuid>`

wherever a command takes a target:

<path|uuid> means a path (refactor/file_1, relative to your scope, leading / for absolute) or a uuid / unambiguous uuid prefix. used by the exact-target verbs (send, logs, attach), which reject wildcards.
<pattern|uuid> additionally allows * and ** wildcards. used by the bulk verbs (wait, kill, ls, and top's filter).

* matches one whole segment; ** matches any depth. there are no partial-segment forms. quote patterns in the shell (kill "review/**") so your shell does not expand them against real files first. the full grammar is in the path grammar reference.

duration units

every duration flag carries a unit: 45s, 20m, 3h. a bare number is rejected with invalid_request. this applies to --timeout, --once-at when given as a relative duration, and the duration keys in config.

confirmation

destructive commands (agent kill, loop run stop, loop rm --kill-active) confirm on a TTY: they list their resolved targets and ask before acting.

-y / --yes skips the prompt.
non-TTY callers and any --json call never prompt; they proceed.

plain loop rm (without --kill-active) is non-destructive (the definition ends but running runs continue), so it does not prompt.

wait-timeout vs agent-timeout

two different timeouts produce two different outcomes:

a wait-style command's own --timeout (agent wait --timeout, loop-related waits) expiring is still a success. the envelope is ok:true, the result is partial (timed_out:true), and the process exits 3. the call succeeded; the targets just had not all settled yet.
an agent's or run's own --timeout expiring is the timeout error code. the agent is killed with exit_reason: timeout, and a wait observing it reports the timeout reason token (exit 5).

see error codes and exit codes for the full nuance.

exit codes

code	meaning
`0`	success (for `wait`: every target settled successfully)
`1`	other (`invalid_request`, `transcript_unavailable`, `server_error`)
`2`	environment (`integration_missing`, `environment_error`)
`3`	timeout (an agent's or run's own deadline; also a wait's own `--timeout`)
`4`	blocked (an agent needs a human)
`5`	killed / ended (a `wait` target died: killed, canceled, timeout, failed, or lost)
`6`	not found
`7`	state conflict (wrong state for the verb; `force_required` for unmanaged kills)

the mapping from each error code to its exit code is in the errors reference.