Synopsis
npx @basemachina/agentic-browser-cli execute -- \
--runbook <path> \
[options]
Required arguments
| Argument | Description |
|---|
--runbook <path> | Path to the runbook YAML file |
Optional arguments
Execution
| Argument | Default | Description |
|---|
--headless <bool> | true | Set to false to show the browser window |
--step-delay <ms> | YAML value | Override pauseBetweenSteps from the YAML |
--skip-confirmation | false | Auto-approve all confirmation prompts |
--output-dir <path> | - | Directory for download and export files |
--merge-downloads | false | Merge downloaded CSV files into one |
Batch execution
| Argument | Default | Description |
|---|
--data <path> | - | CSV or JSON data file for batch execution |
--reuse-session | true | Reuse browser session across batch rows |
--no-reuse-session | - | Start a fresh browser for each batch row |
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) |
--max-retries <num> | - (self-heal: 5) | Maximum selector resolution retries |
--retry-warning-threshold <num> | - (self-heal: 3) | Retry count before warning |
--enable-selector-cache | plan-dependent | Enable selector cache (successful refs persisted) |
--enable-agent-fallback | plan-dependent | Enable Agent Fallback (AI alternative path exploration) |
--enable-vision-fallback | plan-dependent | Enable Vision Fallback (screenshot-based resolution) |
--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> | cli | Approval mode: cli, slack, teams, or discord |
--notify <mode> | - | Notification on completion: slack, teams, or discord |
--callback-port <port> | 3100 | Webhook callback server port |
--approval-timeout <ms> | 300000 | Approval timeout (5 minutes default) |
Slack/Teams/Discord approval requires Business plan or higher. Notifications require Team plan or higher.
export SLACK_BOT_TOKEN="xoxb-..."
export SLACK_SIGNING_SECRET="..."
export SLACK_CHANNEL_ID="C01234567"
export TEAMS_APP_ID="..."
export TEAMS_APP_PASSWORD="..."
export TEAMS_CHANNEL_ID="..."
export DISCORD_BOT_TOKEN="..."
export DISCORD_PUBLIC_KEY="..."
export DISCORD_APPLICATION_ID="..."
export DISCORD_CHANNEL_ID="..."
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 |
Per-purpose model overrides
| Argument | Description |
|---|
--model-selector <id> | Model for selector resolution |
--model-extraction <id> | Model for data extraction |
--model-review <id> | Model for review and repair suggestions (self-heal only) |
--model-fallback <id> | Model for Agent Fallback |
--model-vision <id> | Model for Vision Fallback |
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 @basemachina/agentic-browser-cli execute -- \
--runbook ./login-flow.yaml \
--context ./context.md \
--secrets ./secrets.json \
--headless false \
--model "claude-sonnet-4-6" \
--model-provider anthropic
Instead of passing --model and --model-provider on every command, you can set defaults via environment variables:export AI_MODEL_ID="claude-sonnet-4-6"
export AI_MODEL_PROVIDER="anthropic"
With screenshots
npx @basemachina/agentic-browser-cli execute -- \
--runbook ./login-flow.yaml \
--screenshots ./screenshots
Batch execution with CSV
npx @basemachina/agentic-browser-cli execute -- \
--runbook ./create-users.yaml \
--data ./users.csv
users.csv:
Self-heal mode
npx @basemachina/agentic-browser-cli execute -- \
--runbook ./login-flow.yaml \
--self-heal
With Slack approval
export SLACK_BOT_TOKEN="xoxb-..."
export SLACK_CHANNEL_ID="C01234567"
npx @basemachina/agentic-browser-cli execute -- \
--runbook ./payment-flow.yaml \
--approval-mode slack \
--notify slack
With secrets
npx @basemachina/agentic-browser-cli execute -- \
--runbook ./login-flow.yaml \
--secrets ./secrets.json
Using environment variables for credentials
In your runbook YAML:
variables:
email:
source: env
key: APP_EMAIL
password:
source: secrets
key: APP_PASSWORD
export APP_EMAIL="[email protected]"
npx @basemachina/agentic-browser-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 |
AGENTIC_BROWSER_LOCALE | Default for --locale (en or ja) |
AGENTIC_BROWSER_API_KEY | Default for --api-key |
