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

# execute

> Execute a runbook to automate browser operations.

## Synopsis

```bash theme={null}
npx @refrainai/cli execute -- \
  --runbook <path> \
  [options]
```

Reads a runbook, resolves variables, and executes each step in a browser with self-healing selector resolution.

## Required arguments

| Argument           | Description              |
| ------------------ | ------------------------ |
| `--runbook <path>` | Path to the runbook file |

## Optional arguments

### Execution

| Argument              | Default       | Description                                   |
| --------------------- | ------------- | --------------------------------------------- |
| `--headless <bool>`   | `true`        | Set to `false` to show the browser window     |
| `--step-delay <ms>`   | runbook value | Override `pauseBetweenSteps` from the runbook |
| `--output-dir <path>` | -             | Directory for download and export files       |
| `--merge-downloads`   | `false`       | Merge downloaded CSV files into one           |

### Context & secrets

| Argument           | Default | Description                                                 |
| ------------------ | ------- | ----------------------------------------------------------- |
| `--context <path>` | -       | Path to supplemental context markdown file                  |
| `--secrets <path>` | -       | Path to secrets JSON file (all values treated as sensitive) |

### Output & debugging

| Argument              | Default | Description                                   |
| --------------------- | ------- | --------------------------------------------- |
| `--screenshots <dir>` | -       | Directory to save screenshots                 |
| `--video <dir>`       | -       | Directory for video recording output          |
| `--report`            | `false` | Force generate an execution report (Markdown) |

### Self-healing

| Argument      | Default | Description                                                         |
| ------------- | ------- | ------------------------------------------------------------------- |
| `--self-heal` | `false` | Enable self-healing mode (aggressive retry + AI repair suggestions) |

<Note>
  `--self-heal` enables all self-healing features and sets aggressive defaults. See [self-heal mode](/concepts/plan-tiers#self-healing-mode) for plan requirements.
</Note>

### Approval & notifications

| Argument                 | Default | Description                                                |
| ------------------------ | ------- | ---------------------------------------------------------- |
| `--approval-mode <mode>` | `web`   | Approval mode: `web`, `slack`, `teams`, or `discord`       |
| `--notify <mode>`        | -       | Notification on completion: `slack`, `teams`, or `discord` |

<Note>
  Slack/Teams/Discord approval requires Business plan or higher. Notifications require Team plan or higher.
</Note>

<Note>
  Each platform requires specific environment variables (bot tokens, channel IDs, signing secrets). See [Approval & Notifications](/guides/approval-and-notifications#platform-setup) for complete platform setup instructions.
</Note>

### AI model

| Argument                      | Default             | Description                              |
| ----------------------------- | ------------------- | ---------------------------------------- |
| `--model <id>`                | `claude-sonnet-4-6` | AI model ID                              |
| `--model-provider <provider>` | `anthropic`         | AI provider                              |
| `--model-base-url <url>`      | -                   | Base URL for OpenAI-compatible endpoints |

### Advanced

| Argument          | Default | Description                                       |
| ----------------- | ------- | ------------------------------------------------- |
| `--locale <code>` | `en`    | UI and AI prompt language: `en` or `ja`           |
| `--stealth`       | `false` | Enable stealth mode (bot detection evasion)       |
| `--proxy <url>`   | -       | Proxy URL (e.g., `http://user:pass@host:port`)    |
| `--skill <names>` | -       | Comma-separated skill plugin names                |
| `--api-key <key>` | -       | API key for Pro/Team/Business/Enterprise features |

## Examples

### Basic execution

```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
```

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

### With screenshots

```bash theme={null}
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --screenshots ./screenshots
```

### Self-heal mode

```bash theme={null}
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --self-heal
```

### With Slack approval

```bash theme={null}
export SLACK_BOT_TOKEN="xoxb-..."
export SLACK_CHANNEL_ID="C01234567"

npx @refrainai/cli execute -- \
  --runbook ./payment-flow.yaml \
  --approval-mode slack \
  --notify slack
```

### With secrets

```bash theme={null}
npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --secrets ./secrets.json
```

### Using environment variables and secrets

Pass credentials securely using environment variables and the `--secrets` flag:

```bash theme={null}
export APP_EMAIL="user@example.com"

npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --secrets '{"APP_PASSWORD": "s3cret!"}'
```

## Environment variables

| Variable            | Description                           |
| ------------------- | ------------------------------------- |
| `AI_MODEL_ID`       | Default for `--model`                 |
| `AI_MODEL_PROVIDER` | Default for `--model-provider`        |
| `REFRAIN_LOCALE`    | Default for `--locale` (`en` or `ja`) |
| `REFRAIN_API_KEY`   | Default for `--api-key`               |