Variables & Secrets

Overview

Variables make runbooks reusable. Define them once, and reference them in step values with {{variableName}} syntax. Values can come from interactive prompts, environment variables, context files, secrets, or static values.

Variable sources

Variables are defined in the runbook with a source that determines how their value is resolved:

Source	Description	Example use case
`prompt`	Asks the user at execution time (CLI only)	Login credentials, one-time values
`fixed`	Hardcoded static value	Base URLs, constants
`context`	AI extracts from the `--context` markdown file	Values described in documentation
`env`	Read from an environment variable	`AWS_REGION`, `APP_URL`
`expression`	Evaluate a template expression	`{{Date.now()}}`, computed values
`data`	Read from a data file	Row-specific values in batch workflows

Examples

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

Resolution priority

At execution time, variables are resolved in this order. The first match wins:

Priority	Source	Description
1	secrets	Values from `--secrets` flag or SDK `secrets` option
2	data	Values from data files
3	context	AI extraction from `--context` markdown
4	env	Environment variables
5	expression	Template expression evaluation
6	fixed	Static value from the definition
7	prompt	Interactive prompt (CLI only)

This means secrets always take precedence. If you pass a value via --secrets, it overrides any other source.

Secrets handling

Secrets are sensitive values that should never appear in logs or reports. There are two ways to provide them:

Via `--secrets` flag

Create a JSON file with key-value pairs:

{
  "password": "s3cret!",
  "apiToken": "tok_abc123"
}

npx @refrainai/cli execute -- \
  --runbook ./flow.yaml \
  --secrets ./secrets.json

All values in the secrets file are automatically treated as sensitive and masked in all output.

Via `sensitive: true` flag

Mark individual variables as sensitive in the runbook:

variables:
  password:
    source: prompt
    description: "Login password"
    sensitive: true

Context-based resolution

When a variable has source: context, AI reads the --context markdown file and extracts the value based on the variable’s description. This is useful when values are documented but not hardcoded:

variables:
  adminUrl:
    source: context
    description: "Admin dashboard URL"

# App context

The admin dashboard is at https://admin.example.com/dashboard

AI will resolve adminUrl to https://admin.example.com/dashboard.

Template syntax

Reference variables in any string field using double curly braces:

steps:
  - ordinal: 0
    description: "Navigate to {{baseUrl}}"
    action:
      type: navigate
      url: "{{baseUrl}}/login"
  - ordinal: 1
    description: "Enter email"
    action:
      type: input
      value: "{{email}}"
      selector:
        role: textbox
        ariaLabel: "Email"

Templates support:

Simple references: {{variableName}}
Dot notation for captured objects: {{captured.field}}
Nesting up to 3 levels deep

Best practices

Use prompt for credentials — Never hardcode passwords in runbooks
Use env for environment-specific values — Base URLs, API endpoints, regions
Use context for documented values — Keep context.md as the source of truth
Mark sensitive values — Use sensitive: true or --secrets to ensure masking
Keep secrets out of version control — Add secrets.json to .gitignore

Getting Started

Workflow Guides

Use Cases

Support

Web Console

CLI Reference

SDK

Runbook YAML

Concepts

Variables & Secrets

Overview

Variable sources

Examples

Resolution priority

Secrets handling

Via `--secrets` flag

Via `sensitive: true` flag

Context-based resolution

Template syntax

Best practices

What’s next

YAML Variables reference

Execute a runbook

​Overview

​Variable sources

​Examples

​Resolution priority

​Secrets handling

​Via --secrets flag

​Via sensitive: true flag

​Context-based resolution

​Template syntax

​Best practices

​What’s next

YAML Variables reference

Execute a runbook

Overview

Variable sources

Examples

Resolution priority

Secrets handling

Via `--secrets` flag

Via `sensitive: true` flag

Context-based resolution

Template syntax

Best practices

What’s next