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

# Generate a Runbook

> Let AI explore your web app and build a runbook automatically.

## 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](/guides/execute-runbook) unlimited times with zero AI cost.

## Prerequisites

* **Node.js** 18 or later
* An **AI provider API key** (see [Set Up Your AI Provider](/guides/ai-setup))
* A **context file** (recommended) describing the target app

## Step-by-step

<Steps>
  <Step title="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:

    ```markdown theme={null}
    # 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:

    ```json theme={null}
    {
      "email": "user@example.com",
      "password": "s3cret!"
    }
    ```
  </Step>

  <Step title="Run the generate command">
    ```bash theme={null}
    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:

    | Flag               | Description                                   |
    | ------------------ | --------------------------------------------- |
    | `--url`            | Start URL (required)                          |
    | `--goal`           | What AI should accomplish (required)          |
    | `--output`         | Where to save the runbook (required)          |
    | `--context`        | Path to context markdown file                 |
    | `--secrets`        | Path to secrets JSON file                     |
    | `--headless false` | Show the browser window to watch AI in action |

    See [CLI reference: generate](/cli/generate) for all available flags.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<AccordionGroup>
  <Accordion title="AI gets stuck or goes in circles">
    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.
  </Accordion>

  <Accordion title="AI doesn't achieve the goal">
    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.
  </Accordion>

  <Accordion title="AI takes too many steps">
    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.
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={2}>
  <Card title="Execute a runbook" icon="play" href="/guides/execute-runbook">
    Run your generated runbook.
  </Card>

  <Card title="How it works" icon="lightbulb" href="/concepts/how-it-works">
    Understand the full pipeline.
  </Card>

  <Card title="generate CLI reference" icon="terminal" href="/cli/generate">
    All generate command options.
  </Card>
</CardGroup>