Skip to main content

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.

​
Overview

Variables let you parameterize runbooks. Define them in the variables section and reference them in step values with {{variableName}} syntax.

​
Definition

variables:
  email:
    source: prompt
    description: "Login email address"
    required: true
  password:
    source: prompt
    description: "Login password"
    required: true
    sensitive: true
  baseUrl:
    source: fixed
    value: "https://staging.example.com"
  timestamp:
    source: expression
    expression: "{{Date.now()}}"
  region:
    source: env
    envKey: "AWS_REGION"

​
Variable fields

FieldTypeDefaultDescription
sourceVariableSource—How the variable is resolved (see below)
descriptionstring—Human-readable description
requiredbooleantrueWhether the variable must be resolved before execution
sensitivebooleanfalseMask value in logs and reports
valuestring—Static value (for fixed source)
expressionstring—Template expression (for expression source)
envKeystring—Environment variable name (for env source)

​
Variable sources

SourceDescriptionExample
promptPrompt the user at execution time (CLI only)Login credentials
fixedHardcoded static valueBase URLs, constants
contextAI extracts from the context markdown fileValues described in --context
envRead from an environment variableAWS_REGION, APP_URL
expressionEvaluate a template expression{{Date.now()}}, {{captured_value}}
dataRead from a CSV/JSON data file (batch execution)Row-specific values

​
Resolution priority

At execution time, variables are resolved in priority order: secrets > data > context > env > expression > fixed > prompt. The first match wins. For a detailed breakdown of each source, see Variables & Secrets: Resolution priority.
In SDK mode, prompt source is not available. Unresolved required variables will throw an error.

​
Using variables in steps

Reference variables in any string field using {{variableName}}: 
steps:
  - ordinal: 0
    description: "Navigate to {{baseUrl}}"
    action:
      type: navigate
      url: "{{baseUrl}}/login"
    url: "{{baseUrl}}/login"
    riskLevel: low
    requiresConfirmation: false
  - ordinal: 1
    description: "Enter email"
    action:
      type: input
      value: "{{email}}"
      selector:
        tagName: input
        inputType: email
    url: "{{baseUrl}}/login"
    riskLevel: low
    requiresConfirmation: false

​
Sensitive variables

Mark variables as sensitive: true to prevent their values from appearing in logs and reports: 
variables:
  password:
    source: prompt
    description: "Login password"
    sensitive: true
Values passed via --secrets (CLI) or the secrets option (SDK) are automatically treated as sensitive.

​
Batch execution with data source

When using --data, map variable names to CSV/JSON columns with dataSource: 
variables:
  email:
    source: data
    description: "User email from CSV"
  name:
    source: data
    description: "User name from CSV"

dataSource:
  mapping:
    email: "Email"      # CSV column header
    name: "Full Name"   # CSV column header

npx @refrainai/cli execute -- \
  --runbook ./flow.yaml \
  --data ./users.csv
The runbook executes once per data row, with variables populated from each row.