quickstart: CLI

this runs one agent from the shell and covers the five verbs you will use most: run, wait, logs, send, and kill. it assumes you have finished installation and orcr server status shows a supported provider.

spawn an agent

orcr agent run --name reviewer -a codex -p "Review src/auth.ts for auth bugs. Say DONE."

orcr agent run is always asynchronous. it validates the request, enqueues it, and prints one line to stdout, the agent's absolute path and its uuid, separated by a space:

reviewer 0192f1a4-9c7e-7b3a-8f21-2d6c4e0b9a11

the two identifiers matter later: the path (reviewer here, the last segment is the name) is the live address you target, and the uuid is permanent and never reused. on a terminal, run also prints a hint to stderr with the follow-up commands.

naming is mandatory. pass exactly one of --name <name> (the agent lands in your current scope) or --path <path> (the last segment is the name, the rest is where it lives). there are no auto-generated names.

the -a flag chooses the provider. it is optional and falls back to defaults.agent in your config (default claude). -p is the prompt; -p - reads the prompt from stdin for long prompts.

wait for it to settle

orcr agent wait reviewer

wait blocks until the agent settles: its turn completes (idle), it finishes and its pane is tidied (ended with completed or reaped), or it needs a human (blocked). it prints one line per agent, <path> <reason>:

reviewer turn_complete

exit codes tell a script what happened without parsing: 0 settled successfully, 4 blocked (needs a human), 5 the agent was killed or died, 3 the wait's own --timeout expired, 6 no agent matched.

read the answer

orcr agent logs reviewer --last-response

logs reads the provider's native transcript through orcr's integration. --last-response prints only the final assistant message. it fails loudly rather than guessing: if no final response is identifiable it exits 1 with transcript_unavailable. add --tail <n> for the last n entries and --follow to keep streaming; they compose (--tail 50 --follow).

steer it

orcr agent send reviewer "Also check the refresh-token path."

send types the prompt into the agent's TUI and submits it, whatever state the agent is in. it waits for the pane to confirm delivery and reports delivered_while (the agent's status at delivery) and the new input_seq. sending to a parked agent revives it first. send confirms terminal delivery, not that the provider accepted the input.

clean up

orcr agent kill reviewer -y

kill runs each provider's graceful shutdown recipe and closes the pane. by default it confirms on a terminal by listing the matched agents; -y skips the prompt. it ends the agents with exit_reason: killed; history stays in the store. killing an agent that orcr did not create (an unmanaged one) needs --force.

kill also takes glob patterns for clearing a whole subtree at once, for example orcr agent kill "review/**" -y. wildcards match whole path segments and are anchored, so review/** matches everything under a review scope but never an agent named reviewer.

the one-liner: orcr agent ask

when you want a single request and its answer in one call, use ask:

orcr agent ask --name quick_check -a codex -p "Is src/auth.ts safe against replay? One paragraph."

ask is documented sugar for run --gc immediate, then wait, then logs --last-response. it spawns the agent, blocks through the queue and the first turn, prints the final response to stdout, and closes the pane. a blocked agent exits 4; no identifiable response gives transcript_unavailable. parallel asks need distinct names.

watch the live view

orcr top

orcr top is a live, view-only tree of every active agent arranged by path, with statuses updating in real time and loops shown as subtrees. it is a status display, not a control surface; act on agents with the CLI verbs above. filter with a pattern (orcr top "review/**") or with -a, --status, and --loops.

path rules in one line

paths are relative to your scope (a plain shell has no scope, so relative and absolute are the same there); a leading / anchors to the root; * matches one whole path segment and ** matches any number of segments; wildcards are whole segments only and work only with the bulk verbs; quote patterns in the shell.

next steps

• quickstart: SDK for real control flow in TypeScript.
• your first workflow fans out a review across every changed file.
• the identity model explains paths, scopes, and globs in full.