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

# Execute a Runbook

> Run a generated runbook with deterministic execution and zero AI cost.

## Overview

The `execute` command loads a runbook and replays each step in a browser. Selectors are resolved deterministically — **no AI tokens are consumed** on reruns (except when fallback features are triggered). Whether you run it once or a hundred times, the cost stays at zero.

## Prerequisites

* A generated runbook (see [Generate a Runbook](/guides/generate-runbook))
* An **AI provider API key** (needed only for fallback features)
* A **context file** (if the runbook uses `context` variables)

## Basic execution

<Steps>
  <Step title="Run the execute command">
    ```bash theme={null}
    npx @refrainai/cli execute -- \
      --runbook ./login-flow.yaml \
      --context ./context.md \
      --secrets ./secrets.json \
      --headless false
    ```

    The executor:

    1. Loads the runbook and resolves all [variables](/guides/variables-and-secrets)
    2. Opens a browser and navigates to the start URL
    3. Executes each step using [multi-layered selector resolution](/concepts/selector-resolution)
    4. Reports the result of each step
  </Step>

  <Step title="Provide variable values">
    Variables with `source: prompt` will ask for input at the CLI. Variables from other sources (fixed, env, context, secrets) are resolved automatically.
  </Step>

  <Step title="Review results">
    After execution, a summary shows the status of each step (success, failure, skipped). Use `--report` to generate a detailed Markdown report.
  </Step>
</Steps>

## Advanced options

### Screenshots

Save a screenshot after each step for debugging or audit purposes:

```bash theme={null}
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --screenshots ./screenshots
```

### Video recording

Record the entire execution as a video:

```bash theme={null}
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --video ./recordings
```

<Note>
  Video recording requires [Business or higher](/concepts/plan-tiers).
</Note>

### Downloads and exports

Save downloaded and exported files to a specific directory:

```bash theme={null}
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --output-dir ./output \
  --merge-downloads
```

`--merge-downloads` combines multiple downloaded CSV files into one.

### Approval workflow

Steps marked with `requiresConfirmation: true` pause execution and wait for human approval. By default, approval is handled via the CLI. For team workflows, use Slack, Teams, or Discord.

See [Approval and Notifications](/guides/approval-and-notifications) for setup details.

### Step delay

Control the pause between steps (overrides the runbook's `pauseBetweenSteps` setting):

```bash theme={null}
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --step-delay 1000
```

## When execution fails

If steps fail due to UI changes, you have several options:

1. **Self-heal mode** — Let AI diagnose and suggest fixes: `--self-heal` (see [Self-heal guide](/guides/self-heal))
2. **Debug visually** — Use `--headless false` to watch where it fails
3. **Check screenshots** — Use `--screenshots` to capture the page state at each step
4. **Review the report** — Use `--report` for detailed diagnostics

## What's next

<CardGroup cols={2}>
  <Card title="Self-heal mode" icon="wrench" href="/guides/self-heal">
    Automatically diagnose and fix failures.
  </Card>

  <Card title="Variables and secrets" icon="key" href="/guides/variables-and-secrets">
    Parameterize runbooks with variables.
  </Card>

  <Card title="Approval and notifications" icon="bell" href="/guides/approval-and-notifications">
    Set up Slack/Teams/Discord approval.
  </Card>

  <Card title="execute CLI reference" icon="terminal" href="/cli/execute">
    All execute command options.
  </Card>
</CardGroup>