Skip to main content

​
Overview

The generate command opens a browser, lets AI explore your web app based on a goal you describe, and outputs a structured runbook. The runbook can then be executed unlimited times with zero AI cost.

​
Prerequisites

  • Node.js 18 or later
  • An AI provider API key (see Set Up Your AI Provider)
  • A context file (recommended) describing the target app

​
Step-by-step

1

Prepare context and secrets

Create a context.md file with supplementary information about your target app — login URLs, navigation hints, special UI patterns, and business rules:
# 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
- Use the staging environment, not production
If the workflow needs credentials, create a secrets.json file. All values are treated as sensitive and masked in logs:
{
  "email": "[email protected]",
  "password": "s3cret!"
}
2

Run the generate command

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
Key flags:
FlagDescription
--urlStart URL (required)
--goalWhat AI should accomplish (required)
--outputWhere to save the runbook (required)
--contextPath to context markdown file
--secretsPath to secrets JSON file
--headless falseShow the browser window to watch AI in action
See CLI reference: generate for all available flags.
3

Watch AI explore (optional)

With --headless false, you can watch AI navigate your app in real time.If AI gets stuck or goes off track, you can intervene by pressing Enter or p to pause, then provide guidance or abort.AI will also detect when it’s stuck in a loop and ask for your guidance automatically.
4

Review the generated steps

After exploration, AI reviews all recorded steps:
  • Removes unnecessary steps (redundant clicks, accidental navigations)
  • Assigns risk levels (low, medium, high) to each step
  • Flags high-risk steps for approval (requiresConfirmation: true)
You can modify these flags interactively during the review phase.
5

Get the runbook

The final runbook is saved to the path specified by --output. It contains all steps, selectors, variables, and settings needed for execution.

​
Tips for better results

  • Be specific in your goal — “Log in with email and password, then export the user list as CSV” is better than “Do some stuff on the admin page”
  • Provide rich context — The more information in context.md, the fewer wrong turns AI takes. Include login credentials, page structure notes, and expected behavior.
  • Use --headless false — Watching the exploration helps you catch issues early and provide guidance when needed.
  • Start with simple goals — Break complex workflows into smaller goals, generate separate runbooks, then chain them.

​
Troubleshooting

Press Enter to pause and provide guidance like “Click the Settings menu first” or “The button is at the bottom of the page”. You can also increase --max-iterations if the goal requires many steps.
Check that your context.md has enough detail about the target app. Try making the goal more specific. If the app uses bot detection, try --stealth mode.
The review phase removes unnecessary steps. If the result still has too many, try a more focused goal or add guidance in context.md about the optimal path.

​
What’s next

Execute a runbook

Run your generated runbook.

How it works

Understand the full pipeline.

generate CLI reference

All generate command options.