Skip to main content

​
Overview

The execute command loads a runbook and replays each step in a browser. Selectors are resolved deterministically — no AI tokens are consumed on reruns (except when fallback features are triggered). Whether you run it once or a hundred times, the cost stays at zero.

​
Prerequisites

  • A generated runbook (see Generate a Runbook)
  • An AI provider API key (needed only for fallback features)
  • A context file (if the runbook uses context variables)

​
Basic execution

1

Run the execute command

npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --context ./context.md \
  --secrets ./secrets.json \
  --headless false
The executor:
  1. Loads the runbook and resolves all variables
  2. Opens a browser and navigates to the start URL
  3. Executes each step using multi-layered selector resolution
  4. Reports the result of each step
2

Provide variable values

Variables with source: prompt will ask for input at the CLI. Variables from other sources (fixed, env, context, secrets) are resolved automatically.
3

Review results

After execution, a summary shows the status of each step (success, failure, skipped). Use --report to generate a detailed Markdown report.

​
Advanced options

​
Screenshots

Save a screenshot after each step for debugging or audit purposes: 
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --screenshots ./screenshots

​
Video recording

Record the entire execution as a video: 
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --video ./recordings
Video recording requires Business or higher.

​
Downloads and exports

Save downloaded and exported files to a specific directory: 
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --output-dir ./output \
  --merge-downloads
--merge-downloads combines multiple downloaded CSV files into one.

​
Approval workflow

Steps marked with requiresConfirmation: true pause execution and wait for human approval. By default, approval is handled via the CLI. For team workflows, use Slack, Teams, or Discord. See Approval and Notifications for setup details.

​
Step delay

Control the pause between steps (overrides the runbook’s pauseBetweenSteps setting): 
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --step-delay 1000

​
When execution fails

If steps fail due to UI changes, you have several options:
  1. Self-heal mode — Let AI diagnose and suggest fixes: --self-heal (see Self-heal guide)
  2. Debug visually — Use --headless false to watch where it fails
  3. Check screenshots — Use --screenshots to capture the page state at each step
  4. Review the report — Use --report for detailed diagnostics

​
What’s next

Self-heal mode

Automatically diagnose and fix failures.

Variables and secrets

Parameterize runbooks with variables.

Approval and notifications

Set up Slack/Teams/Discord approval.

execute CLI reference

All execute command options.