> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# orca run and orca chat

> Start a run on an agent and stream it, or talk to a published agent through the public chat gateway.

> **Last updated: 2026-09-06**

`orca run` starts a [run](/concepts/runs) on one of your agents through the conductor API and streams it until it finishes. `orca chat` sends messages to a [published agent](/concepts/publishing) 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](/cli/reference/overview#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](/cli/output-and-scripting).

## orca run

```bash theme={"dark"}
orca run [agent] [prompt...] [--title <title>] [--session <id>] [--detach]
```

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).

| Flag              | Type    | Default                          | Description                                                                                                     |
| ----------------- | ------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `--title <title>` | string  | the prompt, cut to 60 characters | Run title                                                                                                       |
| `--session <id>`  | string  | none                             | Reuse an existing [session](/concepts/sessions); otherwise the server assigns one and returns it as `sessionId` |
| `--detach`        | boolean | `false`                          | Print the run id and exit without tailing                                                                       |

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`](/cli/reference/runs#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.

```bash theme={"dark"}
orca run researcher "Summarize the last three releases" --title "release digest"
RUN_ID=$(orca run researcher "Nightly audit" --detach)
orca run researcher "Nightly audit" --detach --json
```

```json theme={"dark"}
{ "runId": "...", "sessionId": "..." }
```

## orca chat

```bash theme={"dark"}
orca chat [agent] [prompt...] [--key <chat-key>] [--tenant <id>] [--conversation <id>] [--end-user <id>]
```

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`](/cli/reference/agents#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](/cli/authentication)).

| Flag                  | Type   | Default                                         | Description                                                                                 |
| --------------------- | ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `--key <chat-key>`    | string | `ORCA_CHAT_KEY`                                 | Chat key for the published agent                                                            |
| `--tenant <id>`       | string | `ORCA_TENANT`, else resolved from the conductor | Tenant id the agent was published under (`org_...`). Shown as `<slug>` in `cli-v0.5.0` help |
| `--conversation <id>` | string | none                                            | Resume a prior conversation                                                                 |
| `--end-user <id>`     | string | none                                            | Sent to the gateway as `metadata.end_user_id`                                               |

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).

```bash theme={"dark"}
orca chat support-bot "How do I reset my password?" --key "$CHAT_KEY"
echo "What is Orca?" | ORCA_CHAT_KEY=$CHAT_KEY orca chat support-bot --json
```

```json theme={"dark"}
{"event":"delta","data":{"text":"Orca is"}}
```

<Note>
  Verified against orca-cli `cli-v0.5.0`.
</Note>