Skip to main content
Last updated: 2026-09-06
orca run starts a run on one of your agents through the conductor API and streams it until it finishes. orca chat sends messages to a published agent through the public chat gateway, the same surface your end users call, and authenticates with a chat key rather than the tenant API key. Both commands accept the global flags. Both take an optional [agent]: when it is omitted in a terminal an interactive picker opens; in a pipe or script the agent is required (exit code 2). Exit codes are listed on Output and scripting.

​
orca run

Creates a run for agent with prompt (every remaining argument, joined with spaces) and attaches to its event stream until the run reaches a terminal status. The prompt is never read from stdin: in a terminal a missing prompt opens a text input, in a script it is required (exit code 2). What streams depends on the output mode. In a terminal the run renders as a live transcript (assistant text, tool calls and their results, progress) with a spinner while it runs and a final status line carrying the run id, elapsed time, and token usage. When stdout is a pipe, each event is printed as one plain text line and a run <id> finished: <status> line goes to stderr. With --json every event is one JSON object per line; the fields are documented under orca runs tail. The exit code follows the run: 0 when it finishes ok, 1 when it finishes error, cancelled, or interrupted. Ctrl-C detaches the tail only (exit code 130); the run keeps going server-side, and stderr prints the orca runs tail and orca runs cancel commands to reattach or stop it. With --detach, stdout carries only the run id and a started run <id> (session <id>) note goes to stderr; with --detach --json stdout is the create response. Without --detach the run id is only reported on stderr and in the transcript, so use --detach when a script needs to capture it.

​
orca chat

Sends messages to a published agent through the chat gateway (POST /v1/chat/{tenant}/{agent}/stream, always streamed over SSE). agent is the profile name or the published slug. The command needs a chat key, which is separate from the tenant API key the rest of the CLI uses; mint one with orca agents keys create. When [agent] is omitted in a terminal, the picker lists your published agents and needs a signed-in conductor context (see Authentication). How the connection is resolved:
  • Gateway URL: ORCA_GATEWAY_URL, then the gatewayUrl saved in the current context (set with orca auth login --gateway-url <url>), then the built-in production gateway. There is no per-command flag. With none of these set the command fails with exit code 2.
  • Chat key: --key, then ORCA_CHAT_KEY. Missing: exit code 3.
  • Tenant: --tenant, then ORCA_TENANT. When neither is set and the CLI has a signed-in conductor context, it looks the agent up among your published agents by profile name, then by slug, and takes the tenant id and gateway slug from that record. If nothing matches, exit code 2 with a hint to publish the agent or pass --tenant.
Three modes, chosen from the arguments and the terminal:
  • REPL: in a terminal with no prompt, no piped stdin, and no --json, an interactive chat opens. Enter sends, Ctrl-C stops a streaming reply or exits when idle. Turns share one conversation; --conversation seeds it.
  • Single-shot: with a prompt, or with piped stdin (echo hi | orca chat <agent>), one turn runs and the reply is written to stdout with exactly one trailing newline. Tool start notices go to stderr, and only when stderr is a terminal. After the turn, conversation <id> is printed on stderr so a script can capture it and resume with --conversation.
  • --json: single-shot only; a prompt or piped stdin is required. Every SSE frame becomes one line of { "event": <name>, "data": <payload> }; heartbeat comment frames are skipped, and data is the raw string when the payload is not JSON. Event names are delta (text), tool (id, status, and name on the starting frame), done (conversation_id, public_run_id, message), and error (code, message, public_run_id).
Exit codes: 0 when the turn ends with done; 1 when the gateway sends a terminal error event or closes the stream without one; 130 on Ctrl-C. An HTTP rejection before the stream opens maps to 3 (401 or 403), 4 (404, unknown tenant or slug), 2 (400), and 1 (429 or 5xx).
Verified against orca-cli cli-v0.5.0.