# helmr session

URL: https://helmr.dev/docs/reference/cli/session
Description: Operate Actor Sessions and their Turns.

# `helmr session`

```text
helmr session get SESSION_ID [--json]
helmr session send SESSION_ID (--data-json JSON | --data-file FILE) [--json]
helmr session enqueue SESSION_ID (--data-json JSON | --data-file FILE) [--json]
helmr session turn get SESSION_ID TURN_ID [--json]
helmr session turn send SESSION_ID TURN_ID (--data-json JSON | --data-file FILE) [--json]
helmr session turn interrupt SESSION_ID TURN_ID [--json]
helmr session resume SESSION_ID [--hold HOLD_ID] [--json]
helmr session events SESSION_ID [--after N] [--limit N] [--json | --jsonl]
helmr session close SESSION_ID [--json]
helmr session cancel SESSION_ID [--json]
```

Start an Actor with [`helmr actor start`](../actor/), which returns a Session ID
and boot Run ID. These commands address that Session ID. All commands accept
project and environment scope flags. Mutations accept `--idempotency-key KEY`; reuse the key and exact
arguments when retrying an uncertain response. `--json` prints the server
receipt or resource as one JSON object. A receipt acknowledges the operation,
not completion of the work.

## Send work and messages

Commands after start address the server-created Session ID. Application data is
any JSON value; Helmr does not assign meaning to an application's `type` field.

- `send` sends a message to the active Turn or enqueues a new Turn when idle.
  Handler readiness does not gate acceptance: messages wait for delivery to that
  same Turn. A settling Turn or held Session rejects the request; it does not
  silently enqueue replacement work.
- `enqueue` always queues a new Turn, including while another Turn is running
  or an open Session is held.
- `turn send` targets exactly the supplied Turn. Use it for answers, approvals
  and other messages that must never reach a different Turn.

Admission receipts include the Turn ID. `turn get` reports message readiness,
interruption requests, and the final result or error. A failed Turn does not by
itself mean that the Session failed.

## Interrupt and resume

`turn interrupt` requests a stop and returns a hold ID. A `stopping` receipt does
not mean execution has stopped yet. Inspect the Turn and Session to observe
convergence. Queued Turns remain retained and do not start automatically.

`resume` reads the current hold and submits that exact ID. If the hold changes
between the read and the mutation, the server rejects the stale request; the CLI
does not fetch a newer hold and retry. Use `--hold` to target a previously observed
hold, particularly when retrying an uncertain resume with an idempotency key.
Resume permits queued work to proceed; it does not restart the interrupted Turn.

## Read the timeline

`events` reads a finite page of the retained Session timeline: inputs, messages,
output and lifecycle events share one durable sequence. Use `next_after` for the
next page. `--after` is a nonnegative safe integer; `--limit` defaults to 100 and
has a maximum of 1000. `--json` includes pagination and retention metadata;
`--jsonl` emits only records. End of a page or provider output is not Turn
completion. Observe a terminal Turn event or use `turn get` for the outcome.

`close` rejects new ordinary admission and drains already accepted FIFO work. Its
receipt may report `closing` until that work settles. Existing holds remain in
place and must be resolved before held work can drain; close does not interrupt
the active Turn or clear a hold. Use `get` to observe the final Session state.

## Observe automatic recovery

Helmr restores the saved environment after physical cleanup of lost execution.
Use `get` and Session events to observe progress. Completed results remain;
unpublished file changes and uncertain callbacks are not replayed. Ordinary
interruption still requires `resume` with the exact hold.

## Cancel a Session

```sh
helmr session cancel SESSION_ID --project PROJECT --env ENV --idempotency-key stop-review
helmr session get SESSION_ID --project PROJECT --env ENV
```

`cancel` discards queued Turns with a `cancelled` outcome and stops active work.
The response acknowledges acceptance. Wait for Session status `closed` before
Computer deletion; automatic recovery waits for physical cleanup.
Unlike `close`, cancellation does not drain queued work or start new customer code.