Skip to main content

​
Prerequisites

  • Node.js 18 or later
  • An AI provider API key (Anthropic recommended)

​
Install

npx @refrainai/cli generate -- --help

​
AI provider setup

Set your AI provider API key. Anthropic is the default: 
export ANTHROPIC_API_KEY="sk-ant-..."
Refrain supports 7 AI providers (OpenAI, Google, Azure, Bedrock, Vertex, and OpenAI-compatible endpoints). See Set up your AI provider for full setup instructions and environment variables.

​
Step 1: Prepare context and secrets

Before generating a runbook, you can optionally create: context.md — supplementary information about the target app (login URL, navigation hints, special UI patterns, etc.): 
# App context

- Login page: https://app.example.com/login
- After login, the dashboard is at /dashboard
- The "Export CSV" button is in the top-right toolbar
secrets.json — credentials and sensitive values when needed. All values are treated as sensitive: 
{
  "email": "[email protected]",
  "password": "s3cret!"
}

​
Step 2: Generate a runbook

Tell AI what you want to accomplish, and it will explore your web app and build a runbook. 
npx @refrainai/cli generate -- \
  --url "https://app.example.com/login" \
  --goal "Log in and navigate to the dashboard" \
  --output ./login-flow.yaml \
  --context ./context.md \
  --secrets ./secrets.json \
  --headless false \
  --model "claude-sonnet-4-6" \
  --model-provider anthropic
Use --headless false to watch the AI explore your app in real time. Remove it for headless execution.
You can set default model and provider via environment variables instead of passing --model and --model-provider on every command. See default model configuration.
AI will:
  1. Open the browser and navigate to the URL
  2. Explore the page, deciding which actions to take
  3. Record each step (clicks, inputs, navigations)
  4. Review the steps and remove unnecessary ones
  5. Output a clean runbook

​
Step 3: Execute the runbook

Run the generated runbook: 
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --context ./context.md \
  --secrets ./secrets.json \
  --headless false \
  --model "claude-sonnet-4-6" \
  --model-provider anthropic
The execute command resolves selectors 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.
  1. Open the browser and navigate to the starting URL
  2. For each step, resolve the selector to find the target element
  3. Execute the action (click, input, etc.)
  4. Report the results

​
Step 4: Self-heal when UIs change

When the target app’s UI changes and steps start failing, use --self-heal to let AI diagnose and suggest fixes: 
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --context ./context.md \
  --secrets ./secrets.json \
  --self-heal \
  --model "claude-sonnet-4-6" \
  --model-provider anthropic
Self-heal mode enables aggressive retry strategies, AI-powered repair suggestions, and a diagnostic report. Review the suggestions, then apply them with the fix-runbook command: 
npx @refrainai/cli fix-runbook -- \
  --runbook ./login-flow.yaml \
  --report ./login-flow-report.md
With the Web Console, you can generate, execute, schedule, and self-heal runbooks from a browser UI — no CLI required.

​
What’s next?

Generate command

All options for runbook generation.

Execute command

All options for runbook execution.

CLI overview

See all available commands.

Plan tiers

Unlock advanced features with Pro, Team, or Business.