helmr session
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, 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.
sendsends 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.enqueuealways queues a new Turn, including while another Turn is running or an open Session is held.turn sendtargets 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
helmr session cancel SESSION_ID --project PROJECT --env ENV --idempotency-key stop-review
helmr session get SESSION_ID --project PROJECT --env ENVcancel 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.