# helmr actor

URL: https://helmr.dev/docs/reference/cli/actor
Description: Start Actors and operate Sessions and Turns.

# `helmr actor`

```text
helmr actor start ACTOR --workspace WORKSPACE [flags]
helmr actor get SESSION_ID [--json]
helmr actor send SESSION_ID (--data-json JSON | --data-file FILE) [--json]
helmr actor enqueue SESSION_ID (--data-json JSON | --data-file FILE) [--json]
helmr actor turn get SESSION_ID TURN_ID [--json]
helmr actor turn send SESSION_ID TURN_ID (--data-json JSON | --data-file FILE) [--json]
helmr actor turn interrupt SESSION_ID TURN_ID [--json]
helmr actor resume SESSION_ID [--hold HOLD_ID] [--json]
helmr actor events SESSION_ID [--after N] [--limit N] [--json | --jsonl]
helmr actor close SESSION_ID [--json]
```

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.

`start` accepts `--key`, `--idempotency-key`, and managed-Run options: queue,
concurrency key, priority, TTL, tags, metadata, and retry policy. It requires an
existing Workspace. Send the first input separately after starting the Session.

## 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 actor cancel SESSION_ID --project PROJECT --env ENV --idempotency-key stop-review
helmr actor 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
Workspace deletion; automatic recovery waits for physical cleanup.
Unlike `close`, cancellation does not drain queued work or start new customer code.