> ## 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.

# Runbook YAML

> Structure and fields of the runbook YAML format.

## Overview

A **runbook** is a YAML file that describes a sequence of browser automation steps. It is produced by [`generate`](/cli/generate) and consumed by [`execute`](/cli/execute).

## Minimal example

```yaml theme={null}
title: Log in to dashboard
settings:
  baseUrl: "https://app.example.com"
  defaultTimeout: 10000
  pauseBetweenSteps: 500
  stopOnError: true
metadata:
  startUrl: "https://app.example.com/login"
  goal: "Log in and reach the dashboard"
  goalAchieved: true
  totalSteps: 3
  generatedAt: "2025-01-15T10:30:00Z"
steps:
  - ordinal: 0
    description: "Navigate to login page"
    url: "https://app.example.com/login"
    riskLevel: low
    requiresConfirmation: false
    action:
      type: navigate
      url: "https://app.example.com/login"
  - ordinal: 1
    description: "Enter email"
    url: "https://app.example.com/login"
    riskLevel: low
    requiresConfirmation: false
    action:
      type: input
      value: "{{email}}"
      selector:
        tagName: input
        inputType: email
        placeholder: "Email address"
  - ordinal: 2
    description: "Click Sign In"
    url: "https://app.example.com/login"
    riskLevel: medium
    requiresConfirmation: true
    action:
      type: click
      selector:
        tagName: button
        innerText: "Sign In"
variables:
  email:
    source: prompt
    description: "Login email address"
    required: true
```

## Top-level fields

| Field                    | Type    | Required | Description                             |
| ------------------------ | ------- | :------: | --------------------------------------- |
| `title`                  | string  |    Yes   | Human-readable title                    |
| `naturalLanguageSummary` | string  |    No    | AI-generated summary                    |
| `settings`               | object  |    Yes   | Execution settings (see below)          |
| `metadata`               | object  |    Yes   | Generation metadata                     |
| `steps`                  | Step\[] |    Yes   | Ordered list of steps (min 1)           |
| `notes`                  | string  |    No    | Additional notes                        |
| `context`                | string  |    No    | Context markdown                        |
| `variables`              | Record  |    No    | [Variable definitions](/yaml/variables) |
| `dataSource`             | object  |    No    | Data source mapping for batch execution |

## `settings`

| Field               | Type    | Default | Description                         |
| ------------------- | ------- | ------- | ----------------------------------- |
| `baseUrl`           | string  | —       | Base URL of the target application  |
| `defaultTimeout`    | integer | `10000` | Step timeout in milliseconds        |
| `pauseBetweenSteps` | integer | `500`   | Delay between steps in milliseconds |
| `stopOnError`       | boolean | `true`  | Halt execution on first error       |

## `metadata`

| Field          | Type      | Required | Description                                     |
| -------------- | --------- | :------: | ----------------------------------------------- |
| `startUrl`     | string    |    Yes   | URL where generation started                    |
| `goal`         | string    |    Yes   | Goal description                                |
| `goalAchieved` | boolean   |    Yes   | Whether the goal was achieved during generation |
| `totalSteps`   | integer   |    Yes   | Total number of steps                           |
| `generatedAt`  | string    |    Yes   | ISO 8601 timestamp                              |
| `skills`       | string\[] |    No    | Enabled skill plugins                           |

## `dataSource`

Used for batch execution with `--data`.

| Field     | Type                    | Description                                  |
| --------- | ----------------------- | -------------------------------------------- |
| `mapping` | Record\<string, string> | Maps variable names to CSV/JSON column names |

```yaml theme={null}
dataSource:
  mapping:
    email: "Email"
    name: "Full Name"
```

## Step structure

Each step is a `ParsedStep` object. See the sections below for details on each sub-structure:

<CardGroup cols={2}>
  <Card title="Actions" icon="play" href="/yaml/actions">
    12 action types: click, input, select, navigate, scroll, wait, hover, extract, download, export, memory, key
  </Card>

  <Card title="Selectors" icon="crosshairs" href="/yaml/selectors">
    14 selector fields with priority-based resolution
  </Card>

  <Card title="Variables" icon="brackets-curly" href="/yaml/variables">
    6 variable sources with resolution priority
  </Card>

  <Card title="Captures" icon="camera" href="/yaml/captures">
    5 capture strategies to extract data from steps
  </Card>

  <Card title="Loops & Branches" icon="arrows-split-up-and-left" href="/yaml/loops-and-branches">
    while/forEach loops and conditional branching
  </Card>

  <Card title="Memory Operations" icon="database" href="/yaml/memory-operations">
    Append and aggregate data across steps
  </Card>
</CardGroup>

### Common step fields

| Field                  | Type                                        | Required | Description                                                    |
| ---------------------- | ------------------------------------------- | :------: | -------------------------------------------------------------- |
| `ordinal`              | integer                                     |    Yes   | Step sequence number (0-based)                                 |
| `description`          | string                                      |    Yes   | Human-readable step description                                |
| `action`               | [Action](/yaml/actions)                     |    Yes   | Action to perform                                              |
| `url`                  | string                                      |    Yes   | Expected page URL when step executes                           |
| `riskLevel`            | `low` \| `medium` \| `high`                 |    Yes   | Risk classification                                            |
| `requiresConfirmation` | boolean                                     |    Yes   | Whether the step requires user approval before execution       |
| `captures`             | [Capture\[\]](/yaml/captures)               |    No    | Values to capture after execution                              |
| `condition`            | string                                      |    No    | Template expression — step is skipped if it evaluates to falsy |
| `loop`                 | [Loop](/yaml/loops-and-branches)            |    No    | Loop definition                                                |
| `steps`                | Step\[]                                     |    No    | Nested steps (used inside loops)                               |
| `branches`             | [Branch](/yaml/loops-and-branches#branches) |    No    | Conditional branches                                           |
| `memoryOperations`     | [MemoryOp\[\]](/yaml/memory-operations)     |    No    | Memory operations                                              |

<Note>
  A step cannot have both `loop` and `branches` at the same time.
</Note>