> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joystream.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# jstm agent run

> Run an agent, stream its progress, and read the result.

Run an agent and stream execution progress story by story.

```bash theme={null}
jstm agent run month-end-close
jstm agent run month-end-close --input '{"period":"2026-07"}' --verbose
jstm agent run acme-corp/finance/month-end-close --mode dry_run
```

## Options

<ParamField path="AGENT_ID" required>
  The agent to run, as a handle, UUID, or FQN.
</ParamField>

<ParamField path="--mode, -m" default="the agent's deployment stage">
  `dry_run`, `pilot`, or `live`. Omit it and the backend resolves the mode from the agent's current stage — a plain run on a pilot-staged agent runs as pilot, not as an implicit dry run.
</ParamField>

<ParamField path="--input" default="{}">
  Input data as a JSON string.
</ParamField>

<ParamField path="--verbose, -v">
  Show an output preview for each step as it completes.
</ParamField>

<ParamField path="--idempotency-key">
  A key used to deduplicate. Re-sending the same key won't start a second run.
</ParamField>

<ParamField path="--json">
  Emit the result as JSON.
</ParamField>

## Following a run

Progress streams live as the run executes:

```text theme={null}
▶ run started
  ✓ Validate the closing period
  ✓ Pull the general ledger export
  ▶ Reconcile bank statements
```

The stream carries `run_started`, `story_started`, `story_completed`, `story_failed`, `run_completed`, and `run_failed` events. It times out after 300 seconds; the run itself keeps going, and you can rejoin with `jstm agent run show`.

When the run ends, the CLI prints the run id and how to review it.

## When a run needs input

If the agent hits a point where it needs something from a person, it pauses and raises an input request rather than guessing. The CLI prints the exact commands to unblock it:

```text theme={null}
  joystream input-requests show 9b74e2a1-33cd-4f80-a5e6-1d20b8f7c4aa
  joystream input-requests submit 9b74e2a1-33cd-4f80-a5e6-1d20b8f7c4aa --values '{...}'
```

See [`jstm input-requests`](/cli/input-requests).

## `jstm agent run show`

Show a run's status, stories, output, rejection reason, and provenance.

```bash theme={null}
jstm agent run show 5f3a5c81-2d44-4e0b-9a17-0c9d3b7e9b21
jstm agent run show acme-corp/finance/month-end-close/runs/12
```

The second form is a sequence address: `<agent>/runs/N`, where `N` counts from 1 per agent. See [Addressing](/cli/addressing).

<ParamField path="--json">
  Emit the raw payload as JSON.
</ParamField>

Provenance tells you exactly which spec version, agent version, package version, and deployment produced this run.

## Listing runs

```bash theme={null}
jstm agent runs month-end-close
jstm agent runs month-end-close --mode live --status failed
```

| Option     | Description                                             |
| ---------- | ------------------------------------------------------- |
| `--mode`   | Filter by `dry_run`, `pilot`, or `live`                 |
| `--status` | Filter by `queued`, `running`, `completed`, or `failed` |
| `--json`   | Emit as JSON                                            |

Passing a run id instead of an agent id shows that run's full story detail.

## Listing stories

```bash theme={null}
jstm agent stories month-end-close
jstm agent stories --all --status failed
```

| Option     | Description                                                             |
| ---------- | ----------------------------------------------------------------------- |
| `AGENT`    | Agent handle or id. Omit it, or use `--all`, for every agent            |
| `--all`    | Show stories across all agents                                          |
| `--mode`   | Filter by `dry_run`, `pilot`, or `live`                                 |
| `--status` | Filter by `pending`, `in_progress`, `completed`, `failed`, or `skipped` |
| `--json`   | Emit as JSON                                                            |

## See also

* [Runs and work](/concepts/runs-and-work) — runs, epics, stories, tickets.
* [`jstm ticket`](/cli/ticket) — the business-readable view of the same work.
* [Run an agent](/guides/run-an-agent) — walkthrough.