# cs fleet (/docs/cli/fleet)

`cs fleet` drives the agent fleet from a shell: the sessions you see in the
Ensemble app, each one a coding agent in its own sandbox. It speaks the
fleet's own API with the credential `cs` already holds, so there is no
second sign-in: `CS_API_KEY` when it is set, else your
[`cs login`](/docs/cli/login) session.

`cs fleet` is in preview. The fleet has no public address yet, so set
`CS_FLEET_ORIGIN` to the address your organization gave you; without it,
every command except `--help` stops and says so.

## Usage \[#usage]

```bash
cs fleet spawn [--repo <org/name>] [--branch main] [--engine claude|codex]
               [--model <id>] [--effort <level>] [--sandbox <kind> | --machine <id>]
               [--ttl <duration>] [--env <environment-id>|none] <prompt…|->
cs fleet send <id> <text…|->
cs fleet add-repo <id> [<org/name>]
cs fleet peek <id> [--tail <chars>]
cs fleet wait <id> [--timeout 15m]
cs fleet list [--limit 40] [--cursor <c>] [--search <text>] [--owner <user-id>]
              [--repo <org/name>] [--status active|archived|all]
cs fleet archive <id> [--after <duration>]
cs fleet delete <id>
cs fleet models
cs fleet routines [list|create|get|update|pause|resume|run|runs|revisions|archive|unarchive|duplicate|delete|transfer|trigger] …
cs fleet accounts [list|pick|history|rename|delete|setup-token|add|relogin] …
cs fleet stats [--range 7d|30d|90d] [--provider claude|codex] [--window <w>] [--owner <o>] [--timezone <IANA>]
cs fleet tokens [--range 7d|30d] [--owner <o>] [--model <id>] [--timezone <IANA>]
cs fleet tokens backfill [--limit 25]
```

Every command takes `--json`: it prints the fleet's answer as JSON instead
of the view. Durations are `90s`, `15m`, `2h`, `1d` or bare seconds.

```bash
export CS_FLEET_ORIGIN=https://fleet.example.com
cs fleet spawn --repo acme/web "Fix the flaky login test, then open a PR."
cs fleet wait 4f6c…
cs fleet peek 4f6c…
```

## spawn \[#spawn]

`cs fleet spawn <prompt>` starts a session and prints its id and its page.
The prompt is the task: the words after the flags, or, with a lone `-`,
everything on stdin, so a prompt of several paragraphs rides a heredoc.

```bash
cs fleet spawn --repo acme/web --engine codex - <<'EOF'
Read issue #42.

Reproduce it with a failing test, fix it, and open a pull request.
EOF
```

```text title="Output"
Spawned 4f6c0d3e-…
  https://fleet.example.com/a/4f6c0d3e-…
```

* `--repo` is the repository it checks out, as `org/name`; `--branch` is its
  base branch (default `main`). Leave both out for a session with no
  repository. The organization's CoreSpeed GitHub App must reach the
  repository: when it does not, the error names the page that installs it.
* `--engine` picks the coding agent, `claude` (the default) or `codex`.
* `--model` and `--effort` are checked by the fleet; a flag you leave out
  gets the fleet's default. [`cs fleet models`](#models) lists what they may
  name.
* `--sandbox` runs it on one kind of sandbox for this session only:
  `sprites`, `sprites:own` (your organization's own Sprites account) or
  `instabox`. `--machine <id>` runs it on a member's machine through
  [Tie](/docs/cli/tie) instead. Without either, it runs where your
  organization's settings say.
* `--ttl` archives it once it has been quiet that long.
* `--env` pins an environment; `--env none` starts it with none. Without it,
  the session gets the team's default environment.

When the session was made but its sandbox did not start, `spawn` still
prints the id, says why on stderr, and exits 0: the session's page has the
details.

## send and add-repo \[#send-and-add-repo]

`cs fleet send <id> <text>` queues a message for a session; it is delivered
at the end of the session's current turn. `cs` waits up to 30 seconds for
the session's receipt and prints it; with no receipt it exits `7`, and the
message may or may not be queued. A message of several paragraphs rides
stdin, as for `spawn`:

```bash
cs fleet send 4f6c… "pushed fixes at abc123 — re-review"
cs fleet send 4f6c… - < review-notes.md
```

`cs fleet add-repo <id> <org/name>` gives a running session one more
repository; it is the same `/add-repo` command as in the app, so the
session's own check answers it. Without a repository, `add-repo` lists the
ones the session has.

## peek and wait \[#peek-and-wait]

`cs fleet peek <id>` prints the session's status and its newest reply prose:
whole messages, newest last, up to 8,000 characters (`--tail <chars>`
changes that). When older prose was left out, it says so on stderr, and
`--json` sets `tailTruncated`.

```text title="Output"
Review PR #42
  state     idle
  PR        #42
  updated   Oct 23, 08:00 (seq 9)
  url       https://fleet.example.com/a/4f6c0d3e-…

Verdict: APPROVE. CI is green on abc123.
```

`cs fleet wait <id>` blocks until the session's turn ends, then prints its
state. A turn that ended before you ran it counts. It stops after
`--timeout` (default 15 minutes) and exits `7`, so a script can tell "still
working" from a failure:

```bash
cs fleet send "$ID" "pushed fixes — re-review" && cs fleet wait "$ID" --timeout 30m && cs fleet peek "$ID"
```

## list, archive and delete \[#list-archive-and-delete]

`cs fleet list` is the fleet as a table, newest first: one session a line,
with its state, repository, last update and title. `--search` matches
titles, repositories, branches and ids; when there are more, stderr names
the `--cursor` for the next page.

`cs fleet archive <id>` archives a session now; `--after 1h` archives it
once it has been quiet that long. `cs fleet delete <id>` purges an archived
session's transcript for good. The fleet refuses it for a session that is
not archived yet, so a purge always takes two steps.

## models \[#models]

`cs fleet models` lists the models your organization may launch, by engine,
with the efforts each accepts and the defaults a spawn without `--model` or
`--effort` gets. The list is the fleet's, so a model it adds shows here
without a new `cs`.

## routines \[#routines]

A routine is standing work: on a schedule, once at a time, on a GitHub
event, or when an API call fires it, the fleet starts a session with the
routine's prompt (or delivers it into one session). `cs fleet routines` is
the same set of commands an agent uses inside its sandbox.

```bash
cs fleet routines create --name "Nightly audit" --repo acme/web \
  --prompt-file audit.md --cron "7 2 * * *" --tz Asia/Shanghai --expires 2026-12-31
cs fleet routines                       # the team's routines, their next fire and last run
cs fleet routines run <id> --text "after the 2.3 release"
cs fleet routines runs <id> --state failed
cs fleet routines pause <id>
```

* **Triggers.** `--cron "<5 fields>"` with `--tz` (the zone the schedule is
  read in; default, yours), `--window` and `--catchup skip|latest_once`;
  `--at 2026-09-20T09:00` once; `--on-github pull_request:opened,closed`
  with `--gh-repo` and `--gh-filter merged=true` (repeatable); and
  `--api-trigger`. A routine may mix them. Add or remove one later with
  `trigger add` and `trigger rm`; `trigger token` mints an API trigger's
  bearer, shown once.
* **The run.** The `spawn` flags (`--repo`, `--engine`, `--model`,
  `--effort`, `--env`) plus `--time-limit 120m`, `--budget-tokens`,
  `--runs-per-day`, `--overlap skip|queue_one|allow`, `--keep-sessions 4h`,
  `--target session:<id>` to deliver into one session, `--no-continuity`,
  `--notify always|failures|never` and `--expires 2026-12-31` (through the
  end of that day).
* **Templates.** `--template <id>` starts from one of the fleet's templates;
  any flag overrides what it names.
* **Edits.** `update <id>` takes the same flags; `none` clears a field
  (`--repo none`). `--expected-updated-at` refuses the edit when someone
  changed the routine since you read it.
* `create` prints the routine as the fleet saved it, with its next three
  fires, so you confirm the schedule rather than the cron.

`delete` is permanent and takes an archived routine; its past runs and
their sessions stay.

## accounts, stats and tokens \[#accounts-stats-and-tokens]

`cs fleet accounts` is the team's quota board: one seat a line, the hottest
first, with its five-hour and weekly use. `--live` polls the seats first.

```bash
cs fleet accounts
cs fleet accounts pick --model claude-fable-5-1   # which seat a new session would use
cs fleet accounts add --label "Hao's Max"          # sign a seat of your own in
claude setup-token | cs fleet accounts setup-token <id>
```

`add` and `relogin` sign a seat in through your browser: for a Claude seat,
paste the code the page shows; for a codex seat (`add --codex`), enter the
code `cs` prints, and `cs` waits up to ten minutes (exit `7` after that).
`setup-token` reads the token from stdin, never from an argument.

`cs fleet stats` (seat pressure) and `cs fleet tokens` (tokens used and
their estimated cost, never billing) print JSON, in days of your time zone
unless `--timezone` names another. `cs fleet tokens backfill` scans older
transcripts once; running it again is safe.

## Errors \[#errors]

A failure prints `Error: <message>` with one of cs's
[exit codes](/docs/cli#output-and-exit-codes), and `7` when `wait`, `send`
or a seat's sign-in stopped waiting. Each refusal of the fleet says what to do about it:

| You see                                               | What to do                                                                                      |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `CS_FLEET_ORIGIN is not set`                          | Export the fleet's address.                                                                     |
| `the fleet refused your session` (exit `3`)           | Run `cs login`; with `CS_API_KEY` set, check the key.                                           |
| `… is suspended` / `names no organization` (exit `4`) | Signing in again does not help; use a key or session of an active organization.                 |
| `… plan allows …` / `out of credits` (exit `4`)       | Archive a session or a routine, or change the plan or add credits on the billing page it names. |
| `… is not reachable by any GitHub installation`       | Install the CoreSpeed GitHub App on the repository's owner, at the link it names.               |
| `--model: …` / `--effort: …`                          | Pick one that [`cs fleet models`](#models) lists.                                               |
| `no session <id> that you can see`                    | The session (or routine) does not exist, or it is private to someone else.                      |
| `try again` (exit `5`)                                | The fleet or billing could not answer; retry.                                                   |

## Environment variables \[#environment-variables]

| Variable          | Default | Purpose                                              |
| ----------------- | ------- | ---------------------------------------------------- |
| `CS_FLEET_ORIGIN` | none    | The fleet's address. Required.                       |
| `CS_API_KEY`      | unset   | Act with this key instead of the `cs login` session. |