Skip to main content

Overview

A runbook is a YAML file that describes a sequence of browser automation steps. It is produced by generate and consumed by execute.

Minimal example

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

FieldTypeRequiredDescription
titlestringYesHuman-readable title
naturalLanguageSummarystringNoAI-generated summary
settingsobjectYesExecution settings (see below)
metadataobjectYesGeneration metadata
stepsStep[]YesOrdered list of steps (min 1)
notesstringNoAdditional notes
contextstringNoContext markdown
variablesRecordNoVariable definitions
dataSourceobjectNoData source mapping for batch execution

settings

FieldTypeDefaultDescription
baseUrlstringBase URL of the target application
defaultTimeoutinteger10000Step timeout in milliseconds
pauseBetweenStepsinteger500Delay between steps in milliseconds
stopOnErrorbooleantrueHalt execution on first error

metadata

FieldTypeRequiredDescription
startUrlstringYesURL where generation started
goalstringYesGoal description
goalAchievedbooleanYesWhether the goal was achieved during generation
totalStepsintegerYesTotal number of steps
generatedAtstringYesISO 8601 timestamp
skillsstring[]NoEnabled skill plugins

dataSource

Used for batch execution with --data.
FieldTypeDescription
mappingRecord<string, string>Maps variable names to CSV/JSON column names
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:

Common step fields

FieldTypeRequiredDescription
ordinalintegerYesStep sequence number (0-based)
descriptionstringYesHuman-readable step description
actionActionYesAction to perform
urlstringYesExpected page URL when step executes
riskLevellow | medium | highYesRisk classification
requiresConfirmationbooleanYesWhether the step requires user approval before execution
capturesCapture[]NoValues to capture after execution
conditionstringNoTemplate expression — step is skipped if it evaluates to falsy
loopLoopNoLoop definition
stepsStep[]NoNested steps (used inside loops)
branchesBranchNoConditional branches
memoryOperationsMemoryOp[]NoMemory operations
A step cannot have both loop and branches at the same time.