Sessions

Start a cloud agent session with agent "prompt", steer it live, and drive sessions from scripts with agent session get, list, search, connect, stop, diff, and export.

Everything on this page drives a cloud session over the same /v1 API the dashboard uses. What a session is, its statuses, and how it executes: Sessions. Install and authenticate first: Agent CLI.

Start

agent "prompt" starts a session and opens the live conversation. The prompt is the session's instruction; the CLI detects the repository you are standing in (the origin remote) and checks it out in the sandbox.

agent "triage the failing CI on api-repo"
agent -e cloud_agent_environment "triage the failing CI on api-repo"
agent --model claude-sonnet-5 --budget 5 "triage the failing CI on api-repo"
agent -r web-repo -r api-repo "find every caller of the old expiry helper"

With no automation behind it, the session runs your prompt alone: an empty system prompt, no triggers, your organization's default model and environment. Nothing is resolved implicitly. To run a saved automation instead, use agent automation run.

Flags shape one session without a file:

Flag	Effect
`-e, --environment <name>`	Run in a saved environment, by name or id. Not combinable with `--cpu`, `--memory`, or `--timeout`, which override pieces of an environment.
`-r, --repo <owner/name>`	Also check out a repository, in whichever environment the session runs (repeatable; a bare `name` means your account). Composes with `-e`: the checkout is added to the named environment, not replacing it.
`--model <model-id>`	The model for this session (`agent model list`).
`--system <text>`	The system prompt.
`--budget <usd>`	Spend cap for this session, in dollars.
`--cpu <n>`, `--memory <size>`, `--timeout <duration>`	Sandbox sizing, such as `2`, `8GB`, `1h`.
`-f, --config-file <path>`	Start from a config file (YAML or JSON): an automation file, whose `session:` block is used, or a bare session config.
`-t, --template <slug>`	Start from a built-in template (`agent template list`).
`--override <yaml>`, `--override-file <path>`	A partial patch of session config keys merged onto the config; an explicit flag wins over the same field here.
`--rebuild`	Skip the sandbox image cache: a fresh full build whose snapshot refreshes the cache.
`-m, --metadata <key=value>`	Attach metadata (repeatable).

Pass at most one of -f and -t. When the session did not name an environment and your organization has a default one, the CLI reports which the server used (using environment env_4Kq2mP8x (account_default)).

Inside a session

The bare form opens the same view as agent session connect: the conversation so far, live output as it happens, and a composer. Type a message and press Enter; the agent picks it up at its next turn boundary. Ctrl-C once interrupts the running turn (the same as sending /stop), twice leaves the view. The session keeps running, and the CLI prints the command that reopens it:

resume with: agent session connect session_7Hq2mX4p

Esc opens the full-screen session list; pick any of your sessions to read or steer it. The composer appears only for a session that accepts messages: one you started (CLI, API, or dashboard) whose agent is interactive. A session a trigger started opens watch-only with a note saying why: a mention session is steered by replying on its Slack thread, GitHub comment, or Linear issue, and react and cron sessions are single-shot. Watching is never restricted.

agent with no prompt opens the launcher: your running sessions in a sidebar beside a composer, where Enter starts a new cloud session.

From scripts

The bare form is agent session start --connect with the same flags, so the interactive view cannot combine with --watch or --json. Scripts use agent session start directly. By default it returns as soon as the session is created:

$ agent session start "triage the failing CI on api-repo" --budget 5
✓ started session session_7Hq2mX4p (scheduled)
  https://app.ellipsis.dev/your-org?session=session_7Hq2mX4p
  follow with: agent session get session_7Hq2mX4p --watch

-w/--watch blocks instead, streaming live output until the session reaches a terminal status, and exits 0 only when it completes, so it works as a CI gate. --watch --quiet waits without streaming, printing only status transitions and the final summary. --json prints the raw API response (with --watch, one JSON frame per line).

$ agent session start "triage the failing CI on api-repo" --watch
✓ started session session_7Hq2mX4p
  https://app.ellipsis.dev/your-org?session=session_7Hq2mX4p
09:14:03  scheduled
Session scheduled
Session starting…
Starting sandbox…
Preparing image…
Fetching repositories…
Sandbox ready · your-org/api-repo · cached image
09:14:31  running
Bash  (gh run list --repo your-org/api-repo --limit 10)
Read  (api-repo/tests/core/test_expiry.py)
Bash  (cd api-repo && pytest tests/core/test_expiry.py -q)
The failing job is test_expiry_grace_period: the fixture freezes time
before the item is created, so the grace window is already expired when
the assertion runs. Opened your-org/api-repo#512 with the fix.
09:19:47  completed

✓ session session_7Hq2mX4p completed

agent session get shows one session; --watch follows a running one the same way start --watch does, from wherever it is now:

$ agent session get session_7Hq2mX4p
id:        session_7Hq2mX4p
status:    completed
source:    cli
created:   2026-08-31T09:14:03Z
updated:   2026-08-31T09:19:47Z
tokens:    412,338
cost:      $0.87
url:       https://app.ellipsis.dev/your-org?session=session_7Hq2mX4p

agent session get session_7Hq2mX4p --watch          # follow until it finishes; --quiet for the result only
agent session list --limit 20                       # newest first (default 50)
agent session list --automation agent_x9Kd3Fq2      # sessions one automation started, by id or name
agent session list --source cli --author priya-shah --since "3 days ago"
agent session record session_7Hq2mX4p               # the stored transcript, one line per record
agent session export session_7Hq2mX4p -o session.jsonl   # the complete archived log

$ agent session list --limit 3 --source cli
ID                STATUS     SOURCE  CREATED           COST
session_7Hq2mX4p  completed  cli     2026-08-31 09:14  $0.87
session_3Vd8nQ2j  completed  cli     2026-08-30 16:40  $1.42
session_5Kp9wB3n  error      cli     2026-08-30 11:02  $0.19

-s/--source (repeatable) filters on where a session came from: react, manual, api, cli, mention, or cron. -a/--author takes a GitHub login and resolves it against agent github members. --days <n>, --since, and --until bound the window; the last two accept ISO 8601 or the natural forms today, yesterday, and N days ago.

agent session export concatenates the archived log segments and prints them gunzipped (-o writes a file, --gzip keeps the compressed bytes, --json prints the segment manifest instead). While a session is still running, the archive can trail the live feed; the command says so and you re-run it shortly for the rest.

Diff

agent session diff <session-id> prints the session's uncommitted working-tree changes as a unified patch, one diff --git section per changed file, in order, so the output is a patch git apply reads whole.

$ agent session diff session_7Hq2mX4p
diff --git a/api-repo/tests/core/test_expiry.py b/api-repo/tests/core/test_expiry.py
index 3c1f9a2..b7e4d10 100644
--- a/api-repo/tests/core/test_expiry.py
+++ b/api-repo/tests/core/test_expiry.py
@@ -12,8 +12,8 @@ def test_expiry_grace_period(frozen_clock):
-    frozen_clock.set("2026-01-01T00:00:00Z")
     item = create_item()
+    frozen_clock.set("2026-01-01T00:00:00Z")
     assert not item.is_expired()

-o/--output <path> writes the patch to a file and prints the path instead of the patch; --json prints the raw response (each file with its patch, plus omitted_paths). Files whose hunks were too large to store are dropped from the patch and named in a stderr note, so a partial patch is never silently partial:

note: 1 file omitted (too large to store): package-lock.json

A session with a clean tree, or one whose changes were never captured, prints No uncommitted changes were captured for this session. to stderr and nothing to stdout.

Connect

agent session connect <session-id> opens a running session in the view described above. Inside an Ellipsis sandbox the id is optional: the current session is used.

agent session connect session_7Hq2mX4p              # read, follow live, and send messages
agent session connect session_7Hq2mX4p --no-input   # follow read-only (no composer), for scripts
agent session connect session_7Hq2mX4p --no-records # skip replaying prior records on open

Stop

$ agent session stop session_7Hq2mX4p
✓ stopped session session_7Hq2mX4p (stopped)

Search

agent session search searches your team's whole session history across four arms at once: transcript text, recap text, created pull requests, and recap similarity. Results are grouped by session, newest first, with the matching snippet under each.

$ agent session search "expiry grace period" --since "3 days ago"
session_7Hq2mX4p  completed  priya-shah  2 days ago  matched: records, recap
    Traced the flaky test_expiry_grace_period failure to a fixture that freezes time before the item exists.
    6 matching records
session_3Vd8nQ2j  completed  marcus-lee  3 days ago  matched: records
    the expiry job re-reads the grace window from settings on every tick
    2 matching records

Inspect one: agent session get <session-id>. Full history: agent session export <session-id>

A PR-shaped query (#512, api-repo#512, or a pull request URL) also finds the session that created that exact pull request:

agent session search "your-org/api-repo#512"
agent session search "webhook retries" --author marcus-lee --since "3 days ago"

Narrow further with -r/--repo, -s/--source (repeatable), --status (repeatable: scheduled, creating_sandbox, running, retrying, completed, error, cancelled, stopped), --automation (an automation id, repeatable), --session (repeatable), --scope records|recaps|both, and -l/--limit (default 20, up to 100). -a/--author and --since/--until work as on list.