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

# roark simulation run

> Run a simulation

Starts a simulation and returns the run. Send `template` to run one of the built-in templates: it supplies the metrics and checks, and for some templates the flows too, so the request only names the agent and the direction. Send `plan` to describe a simulation yourself and run it once. Send `planId` to run a plan you already have. `template` and `plan` both resolve to a run plan, returned as `simulationRunPlanId`. Add `saveAsPlan` to keep it, or read it back to see exactly what ran. A plan built from a template is a snapshot: retuning the template later never changes what that plan runs, which is what makes a saved one safe to pin in CI.

```bash Synopsis theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark simulation run [options]
```

> [!NOTE]
>
> Calls `POST /v1/simulation/run`

## Request body

This endpoint accepts one of several request shapes, so the body is supplied as
JSON through `--data` or on standard input rather than as individual flags.

**RunSimulationFromConfig** `object`

Requires `plan`

**RunSimulationFromPlanId** `object`

Requires `planId`

**RunSimulationFromTemplate** `object`

Requires `template`, `agentEndpoints`, `direction`

## Example

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark simulation run --data '{ ... }'
```

Every command also takes the [global options](/cli-reference/overview.md#global-options) and sets one
of the [exit codes](/cli-reference/overview.md#exit-codes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.