> ## 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.

# Quickstart

> Get up and running with Refrain in 5 minutes.

## Prerequisites

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

## Install

<CodeGroup>
  ```bash npx (no install) theme={null}
  npx @refrainai/cli generate -- --help
  ```

  ```bash npm theme={null}
  npm install -g @refrainai/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @refrainai/cli
  ```
</CodeGroup>

### AI provider setup

Set your AI provider API key. Anthropic is the default:

```bash theme={null}
export ANTHROPIC_API_KEY="sk-ant-..."
```

<Tip>
  Refrain supports 7 AI providers (OpenAI, Google, Azure, Bedrock, Vertex, and OpenAI-compatible endpoints). See [Set up your AI provider](/guides/ai-setup) for full setup instructions and environment variables.
</Tip>

## 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.):

```markdown theme={null}
# 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:

```json theme={null}
{
  "email": "user@example.com",
  "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.

```bash theme={null}
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
```

<Tip>
  Use `--headless false` to watch the AI explore your app in real time. Remove it for headless execution.
</Tip>

<Tip>
  You can set default model and provider via environment variables instead of passing `--model` and `--model-provider` on every command. See [default model configuration](/guides/ai-setup#default-model).
</Tip>

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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
npx @refrainai/cli fix-runbook -- \
  --runbook ./login-flow.yaml \
  --report ./login-flow-report.md
```

<Tip>
  With the [Web Console](/concepts/plan-tiers), you can generate, execute, schedule, and self-heal runbooks from a browser UI — no CLI required.
</Tip>

## What's next?

<CardGroup cols={2}>
  <Card title="Generate command" icon="wand-magic-sparkles" href="/cli/generate">
    All options for runbook generation.
  </Card>

  <Card title="Execute command" icon="play" href="/cli/execute">
    All options for runbook execution.
  </Card>

  <Card title="CLI overview" icon="terminal" href="/cli/overview">
    See all available commands.
  </Card>

  <Card title="Plan tiers" icon="credit-card" href="/concepts/plan-tiers">
    Unlock advanced features with Pro, Team, or Business.
  </Card>
</CardGroup>