execute

Synopsis

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)

--self-heal enables all self-healing features and sets aggressive defaults. See self-heal mode for plan requirements.

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`

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

Each platform requires specific environment variables (bot tokens, channel IDs, signing secrets). See Approval & Notifications for complete platform setup instructions.

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

npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --context ./context.md \
  --secrets ./secrets.json \
  --headless false \
  --model "claude-sonnet-4-6" \
  --model-provider anthropic

Set default model and provider via environment variables instead of passing them on every command. See default model configuration.

With screenshots

npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --screenshots ./screenshots

Self-heal mode

npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --self-heal

With Slack approval

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

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:

export APP_EMAIL="[email protected]"

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`

Getting Started

Workflow Guides

Use Cases

Support

Web Console

CLI Reference

SDK

Runbook YAML

Concepts

Synopsis

Required arguments

Optional arguments

Execution

Context & secrets

Output & debugging

Self-healing

Approval & notifications

AI model

Advanced

Examples

Basic execution

With screenshots

Self-heal mode

With Slack approval

With secrets

Using environment variables and secrets

Environment variables

​Synopsis

​Required arguments

​Optional arguments

​Execution

​Context & secrets

​Output & debugging

​Self-healing

​Approval & notifications

​AI model

​Advanced

​Examples

​Basic execution

​With screenshots

​Self-heal mode

​With Slack approval

​With secrets

​Using environment variables and secrets

​Environment variables

Synopsis

Required arguments

Optional arguments

Execution

Context & secrets

Output & debugging

Self-healing

Approval & notifications

AI model

Advanced

Examples

Basic execution

With screenshots

Self-heal mode

With Slack approval

With secrets

Using environment variables and secrets

Environment variables