Overview
A runbook is a YAML file that describes a sequence of browser automation steps. It is produced bygenerate and consumed by execute.
Minimal example
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 |
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 |
Step structure
Each step is aParsedStep object. See the sections below for details on each sub-structure:
Actions
12 action types: click, input, select, navigate, scroll, wait, hover, extract, download, export, memory, key
Selectors
14 selector fields with priority-based resolution
Variables
6 variable sources with resolution priority
Captures
5 capture strategies to extract data from steps
Loops & Branches
while/forEach loops and conditional branching
Memory Operations
Append and aggregate data across steps
Common step fields
| Field | Type | Required | Description |
|---|---|---|---|
ordinal | integer | Yes | Step sequence number (0-based) |
description | string | Yes | Human-readable step description |
action | Action | 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[] | No | Values to capture after execution |
condition | string | No | Template expression — step is skipped if it evaluates to falsy |
loop | Loop | No | Loop definition |
steps | Step[] | No | Nested steps (used inside loops) |
branches | Branch | No | Conditional branches |
memoryOperations | MemoryOp[] | No | Memory operations |
A step cannot have both
loop and branches at the same time.