Quickstart

Prerequisites

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

Install

npx @refrainai/cli generate -- --help

npm install -g @refrainai/cli

pnpm add -g @refrainai/cli

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:

Open the browser and navigate to the URL
Explore the page, deciding which actions to take
Record each step (clicks, inputs, navigations)
Review the steps and remove unnecessary ones
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.

Open the browser and navigate to the starting URL
For each step, resolve the selector to find the target element
Execute the action (click, input, etc.)
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.

Getting Started

Workflow Guides

Use Cases

Support

Web Console

CLI Reference

SDK

Runbook YAML

Concepts

Prerequisites

Install

AI provider setup

Step 1: Prepare context and secrets

Step 2: Generate a runbook

Step 3: Execute the runbook

Step 4: Self-heal when UIs change

What’s next?

Generate command

Execute command

CLI overview

Plan tiers

​Prerequisites

​Install

​AI provider setup

​Step 1: Prepare context and secrets

​Step 2: Generate a runbook

​Step 3: Execute the runbook

​Step 4: Self-heal when UIs change

​What’s next?

Generate command

Execute command

CLI overview

Plan tiers

Prerequisites

Install

AI provider setup

Step 1: Prepare context and secrets

Step 2: Generate a runbook

Step 3: Execute the runbook

Step 4: Self-heal when UIs change

What’s next?