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

# Action Commands

> Interact with page elements: click, fill, type, press, select, check, uncheck, hover, and scroll.

# Action Commands

Individual interaction commands for when you need fine-grained control. For multi-step flows, prefer [composite actions](/cli/composite-actions) with `bap act`.

## click

Click an element.

<CodeGroup>
  ```bash By snapshot ref theme={null}
  bap click e5
  ```

  ```bash By ARIA role theme={null}
  bap click role:button:"Submit"
  ```

  ```bash By visible text theme={null}
  bap click text:"Sign in"
  ```

  ```bash By stable ref from observe theme={null}
  bap click @ep44e3j
  ```
</CodeGroup>

<ParamField path="selector" type="string" required>
  Element selector. See [Selectors](#selectors) below.
</ParamField>

## fill

Fill an input field. Clears existing content first.

```bash theme={null}
bap fill label:"Email" "user@example.com"
bap fill e5 "user@example.com"
bap fill placeholder:"Search..." "headphones"
```

<ParamField path="selector" type="string" required>
  Element selector targeting the input field.
</ParamField>

<ParamField path="value" type="string" required>
  The text value to fill.
</ParamField>

<Tip>
  Use `fill` for form fields. It clears existing content and sets the value in one step. Use `type`
  only when you need character-by-character input (e.g., autocomplete, search-as-you-type).
</Tip>

## type

Type text character by character into the focused element. Triggers `keydown`, `keypress`, and `keyup` events for each character.

```bash theme={null}
bap type "browser agent protocol"
```

<ParamField path="text" type="string" required>
  The text to type character by character.
</ParamField>

<Note>
  `type` does not clear existing content. It appends to whatever is already in the field. For form
  fields, prefer `fill`.
</Note>

## press

Press a keyboard key or shortcut.

<CodeGroup>
  ```bash Single key theme={null}
  bap press Enter
  bap press Tab
  bap press Escape
  ```

  ```bash Keyboard shortcut theme={null}
  bap press Control+a
  bap press Meta+c
  ```
</CodeGroup>

<ParamField path="key" type="string" required>
  Key name (e.g., `Enter`, `Tab`, `Escape`, `ArrowDown`, `Control+a`).
</ParamField>

## select

Select an option from a dropdown.

```bash theme={null}
bap select label:"Country" "Canada"
bap select e8 "Option B"
```

<ParamField path="selector" type="string" required>
  Selector targeting the `<select>` element.
</ParamField>

<ParamField path="value" type="string" required>
  The option value or visible text to select.
</ParamField>

## check / uncheck

Toggle checkboxes.

```bash theme={null}
bap check label:"I agree to the terms"
bap uncheck e12
```

<ParamField path="selector" type="string" required>
  Selector targeting the checkbox element.
</ParamField>

## hover

Hover over an element. Useful for triggering hover menus or tooltips.

```bash theme={null}
bap hover role:menuitem:"Products"
bap hover text:"More options"
```

<ParamField path="selector" type="string" required>
  Selector targeting the element to hover over.
</ParamField>

## scroll

Scroll the page or scroll an element into view.

<CodeGroup>
  ```bash Scroll down (default) theme={null}
  bap scroll
  bap scroll down
  ```

  ```bash Scroll with pixel amount theme={null}
  bap scroll down --pixels=500
  bap scroll up --pixels=200
  ```

  ```bash Scroll element into view theme={null}
  bap scroll role:button:"Load More"
  ```

  ```bash Horizontal scroll theme={null}
  bap scroll left --pixels=300
  bap scroll right
  ```
</CodeGroup>

<ParamField path="direction" type="string" default="down">
  Scroll direction: `up`, `down`, `left`, `right`.
</ParamField>

<ParamField path="--pixels" type="number" default="300">
  Number of pixels to scroll.
</ParamField>

<ParamField path="selector" type="string">
  When provided, scrolls the element into view instead of scrolling the page.
</ParamField>

## Selectors

All action commands accept the same selector formats:

| Selector               | Example                   | When to use                                    |
| ---------------------- | ------------------------- | ---------------------------------------------- |
| `e<N>`                 | `e15`                     | From snapshot refs (playwright-cli compatible) |
| `@<ref>`               | `@ep44e3j`                | Stable ref from `bap observe`                  |
| `role:<role>:"<name>"` | `role:button:"Submit"`    | By ARIA role and name (recommended)            |
| `text:"<content>"`     | `text:"Sign in"`          | By visible text                                |
| `label:"<text>"`       | `label:"Email"`           | Form fields by label                           |
| `placeholder:"<text>"` | `placeholder:"Search..."` | By placeholder text                            |
| `testid:"<id>"`        | `testid:"submit-btn"`     | By `data-testid`                               |
| `css:<selector>`       | `css:.btn-primary`        | CSS selector (last resort)                     |
| `xpath:<path>`         | `xpath://button`          | XPath selector (last resort)                   |
| `coords:<x>,<y>`       | `coords:100,200`          | By page coordinates                            |

<Warning>
  Never copy CSS selectors from browser DevTools. They break across deployments. Prefer semantic
  selectors (`role:`, `label:`, `text:`) that survive DOM changes.
</Warning>