> ## 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 sessions

> List and inspect persisted agent sessions and their run history.

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

`orca sessions` inspects [sessions](/concepts/sessions), the persisted state an agent keeps across runs. Sessions are created by `orca run`; pass `--session <id>` to [`orca run`](/cli/reference/run-and-chat#orca-run) to continue one.

Every subcommand accepts the [global flags](/cli/reference/overview#global-flags). `orca sessions get` takes a required `<id>`; there is no interactive picker.

## orca sessions list

```bash theme={"dark"}
orca sessions list [--agent <name>] [--limit <n>] [--offset <n>] [--all]
```

Lists sessions. `--agent` is an exact profile-name match, sent to the server as a filter so the paging total reflects the filtered set; the CLI also filters client-side for servers that predate the filter.

| Flag             | Type    | Default | Description                                                        |
| ---------------- | ------- | ------- | ------------------------------------------------------------------ |
| `--agent <name>` | string  | none    | Only sessions for this exact profile name                          |
| `--limit <n>`    | integer | `10`    | Page size                                                          |
| `--offset <n>`   | integer | `0`     | Page offset                                                        |
| `--all`          | boolean | `false` | Fetch every page (cannot be combined with `--limit` or `--offset`) |

```bash theme={"dark"}
orca sessions list --agent researcher --json | jq -r '.[] | [.id, .status, .runCount] | @tsv'
```

Plain (piped) output is one tab-separated row per session: `id`, `profile`, `runtime`, `status`, `lastUsedAt` (as `YYYY-MM-DD HH:MM`), `runCount`. `--json` prints an array of session objects with `id`, `profile`, `runtime`, `status` (`idle`, `running`, `errored`, or `shutdown`), `createdAt`, `lastUsedAt`, `runCount`, and, when the server has them, `lastPrompt`, `lastRunStartedAt`, `lastRunFinishedAt`, and `lastRunStatus`. The terminal view adds a `last used` and `runs` column and a status glyph. When there are no sessions, stdout stays empty and a hint goes to stderr.

## orca sessions get

```bash theme={"dark"}
orca sessions get <id>
```

Shows one session with its run history. The history comes from a second request; if that request fails the session still prints, with an empty `runs` array in JSON and no recent-runs table in the terminal.

```bash theme={"dark"}
orca sessions get "$SESSION_ID" --json | jq '.runs[0]'
```

`--json` prints the session object plus a `runs` array of run summaries (`id`, `subTask`, `status`, `startedAt`, `finishedAt`). The plain view prints tab-separated key and value rows for `id`, `profile`, `runtime`, `status`, `created`, `lastUsed`, `runCount`, and `lastRunStatus` (`-` when absent); the run list is not part of plain output. The terminal view shows the same fields as a panel, plus the last prompt and up to 5 recent runs (id, status, started, duration).

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