> ## Documentation Index
> Fetch the complete documentation index at: https://piyushvyas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Record, parameterize, and replay deterministic browser workflows as YAML

BAP workflows are YAML files that define a sequence of browser steps. Record them interactively, edit the YAML to add parameters and assertions, then replay them deterministically.

## Recording a Workflow

<Steps>
  <Step title="Start recording">
    ```bash theme={null}
    bap workflow record checkout-flow
    ```

    Recording state is persisted to `~/.bap/recording.json` so it survives across CLI invocations.
  </Step>

  <Step title="Execute your browser commands as normal">
    ````bash bap goto https://store.example.com bap act click:text:"Add to cart" bap act theme={null}
    click:text:"Checkout" bap fill label:"Email" "user@example.com" bap act click:role:button:"Place
    Order" bap screenshot ``` Each command is automatically captured as a workflow step.
    </Step>

    <Step title="Stop recording and save">
      ```bash
      bap workflow stop
      # Saved to ~/.bap/workflows/checkout-flow.yaml
    ````
  </Step>
</Steps>

## YAML Format

A recorded workflow produces YAML like this:

```yaml theme={null}
name: checkout-flow
description: Recorded on 2026-03-21T10:30:00.000Z
steps:
  - type: goto
    args: https://store.example.com
  - type: act
    args: click:text:"Add to cart"
  - type: act
    args: click:text:"Checkout"
  - type: fill
    args: label:"Email"="user@example.com"
  - type: act
    args: click:role:button:"Place Order"
  - type: screenshot
    args: ""
```

## Parameters

Add parameterized values so workflows can be reused with different inputs:

```yaml theme={null}
name: checkout-flow
description: Parameterized checkout workflow
params:
  email: user@example.com
  product: "Widget Pro"
steps:
  - type: goto
    args: https://store.example.com
  - type: act
    args: click:text:"{{product}}"
  - type: fill
    args: label:"Email"="{{email}}"
  - type: act
    args: click:role:button:"Place Order"
```

Run with parameter overrides:

```bash theme={null}
bap workflow run checkout-flow --param email=other@test.com --param product="Gadget X"
```

## Assertions

Add post-step assertions to validate workflow correctness:

```yaml theme={null}
steps:
  - type: goto
    args: https://store.example.com
    assert:
      url: store.example.com
      text: "Welcome to our store"

  - type: act
    args: click:role:button:"Place Order"
    assert:
      url: /confirmation
      text: "Order confirmed"
      element: role:heading:"Thank you"
```

Three assertion types are available:

| Assertion | What it checks                           |
| --------- | ---------------------------------------- |
| `url`     | URL contains the given string            |
| `text`    | Text is visible on the page              |
| `element` | Element matching the BAP selector exists |

## Step Labels

Add human-readable labels for clearer output:

```yaml theme={null}
steps:
  - type: goto
    args: https://store.example.com
    label: Open store homepage

  - type: act
    args: click:text:"Add to cart"
    label: Add product to cart
```

## Repeat and Conditionals

### Repeat a step N times

```yaml theme={null}
steps:
  - type: scroll
    args: "300"
    repeat: 5
    label: Scroll down 5 times
```

### Repeat until a condition is met

```yaml theme={null}
steps:
  - type: act
    args: click:text:"Load more"
    repeat:
      until: "text:No more items"
    label: Load all items
```

### Conditional execution

```yaml theme={null}
steps:
  - type: act
    args: click:text:"Accept cookies"
    if: "element:text:Accept cookies"
    label: Dismiss cookie banner if present
```

## Macros

Define reusable step sequences:

```yaml theme={null}
name: multi-product-checkout
macros:
  add-product:
    params:
      product: ""
    steps:
      - type: act
        args: click:text:"{{product}}"
      - type: act
        args: click:role:button:"Add to cart"

steps:
  - type: goto
    args: https://store.example.com

  - type: macro
    macro: add-product
    macroParams:
      product: "Widget Pro"

  - type: macro
    macro: add-product
    macroParams:
      product: "Gadget X"

  - type: act
    args: click:text:"Checkout"
```

## Error Handling

Control what happens when a step fails:

```yaml theme={null}
name: resilient-workflow
onError: continue # stop (default), continue, or retry
steps:
  - type: act
    args: click:text:"Optional banner"
  - type: goto
    args: https://example.com
```

## Per-Step Timeout

```yaml theme={null}
steps:
  - type: goto
    args: https://slow-site.example.com
    timeout: 60000
    label: Wait up to 60s for slow page
```

## Fused Observation

Add `observe: true` to any step to get a page observation after it executes:

```yaml theme={null}
steps:
  - type: goto
    args: https://example.com
    observe: true
    label: Navigate and observe
```

## Managing Workflows

```bash theme={null}
# List saved workflows
bap workflow list

# Run a workflow
bap workflow run checkout-flow

# Run with parameter overrides
bap workflow run checkout-flow --param email=test@example.com

# Record a reusable macro
bap workflow macro login-steps
# ... execute login commands ...
bap workflow macro stop

# List available macros
bap workflow macros
```

Workflows are saved to `~/.bap/workflows/` as YAML files.

## Step Types

| Type         | What it does       | Example args                    |
| ------------ | ------------------ | ------------------------------- |
| `goto`       | Navigate to URL    | `https://example.com`           |
| `act`        | Composite action   | `click:text:"Submit"`           |
| `click`      | Click element      | `role:button:"OK"`              |
| `fill`       | Fill input         | `label:"Email"="user@test.com"` |
| `observe`    | Observe page       | (empty)                         |
| `extract`    | Extract data       | `--fields="title,price"`        |
| `screenshot` | Take screenshot    | (empty)                         |
| `scroll`     | Scroll page        | `300`                           |
| `wait`       | Wait for condition | `text:"Loaded"`                 |
| `macro`      | Invoke a macro     | (uses `macro` field)            |