Start a run
The run uses the agent’s current stage. A pilot-staged agent runs as pilot; a live-staged agent runs live. To override:
Without --mode, a run on a live-staged agent has real side effects. Pass --mode dry_run explicitly when you want a safe run of an agent that is already in production.
--input takes a JSON string and defaults to {}. The fields an agent accepts come from its spec — jstm agent view <agent> --definition shows them.
If you omit a required input, the run raises an input request rather than failing.
Follow the progress
Progress streams as the run executes:
Add --verbose to see an output preview for each completed step:
The stream times out after 300 seconds. The run itself keeps going — rejoin it with jstm agent run show.
When the run needs you
If the agent reaches a point that requires a person, it pauses and prints how to unblock it:
Read the request first to learn the field names:
Then answer it:
You can address the request by agent instead of by id, when the agent has exactly one open request:
Avoid duplicate runs
When something might retry — a script, a webhook handler — pass an idempotency key:
Re-sending the same key won’t start a second run.
After the run
This gives you status, stories, output, any rejection reason, and provenance — the exact spec, agent, package, and deployment versions that ran.
See Review runs and tickets for reading results in depth.
Scripting a run
Results go to stdout and diagnostics to stderr, so the JSON is safe to pipe:
See also
