Synopsis
npx @refrainai/cli execute -- \
--runbook <path> \
[options]
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
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 |
