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

# GSD Browser Interaction Commands: click, type, scroll, drag

> Complete reference for GSD Browser interaction commands: snapshot, click, type, press, hover, scroll, drag, select, file upload, and viewport control.

Interaction commands let you act on page elements the way a real user would — clicking buttons, filling in forms, scrolling, dragging, and more. Most commands accept either a CSS selector or a versioned snapshot ref (e.g. `@v1:e3`). Refs are generated by `gsd-browser snapshot` and are the preferred approach because they are stable, versioned, and fully described by the browser's internal element model. Always re-run `gsd-browser snapshot` after navigation or significant DOM changes before using refs from a previous snapshot.

***

## `gsd-browser snapshot`

Scan the page and assign versioned refs (`@vN:eM`) to interactive elements. Refs returned by a snapshot are valid until the page changes; after any navigation or DOM mutation, take a fresh snapshot before using ref-based commands.

```bash theme={null}
gsd-browser snapshot [flags]
```

<ParamField query="--mode" type="string">
  Focus the snapshot on a subset of elements. Accepted values:

  | Mode                    | What it captures                           |
  | ----------------------- | ------------------------------------------ |
  | `interactive` (default) | Buttons, inputs, links, and selects        |
  | `form`                  | Form fields with current values and labels |
  | `dialog`                | Content inside open modals or dialogs      |
  | `navigation`            | Navigation links and menus                 |
  | `errors`                | Error messages and validation hints        |
  | `headings`              | `h1`–`h6` elements                         |
  | `visible_only`          | Every visible element on the page          |
</ParamField>

<ParamField query="--selector" type="string">
  Scope the snapshot to a specific region of the page using a CSS selector.
</ParamField>

<ParamField query="--limit" type="number">
  Maximum number of elements to include. Defaults to `40`. Increase this on complex single-page apps.
</ParamField>

**Examples**

```bash theme={null}
# Default snapshot — interactive elements
gsd-browser snapshot

# Snapshot only the sign-up form
gsd-browser snapshot --selector "#signup-form" --mode form

# Capture more elements on a dense UI
gsd-browser snapshot --limit 80

# Snapshot visible content for a broad audit
gsd-browser snapshot --mode visible_only
```

***

## `gsd-browser get-ref`

Retrieve metadata for a specific element ref, including its bounding box, ARIA role, CSS selector, and structural signature. Use this to inspect an element before interacting with it or to debug a stale-ref problem.

```bash theme={null}
gsd-browser get-ref <ref>
```

<ParamField path="ref" type="string" required>
  A versioned ref string in `@vN:eM` format, as returned by `gsd-browser snapshot`.
</ParamField>

**Example**

```bash theme={null}
gsd-browser snapshot
gsd-browser get-ref @v1:e3
# Prints: role, name, bounding box, selector hint, structural signature
```

***

## `gsd-browser click`

Click an element identified by a CSS selector or by exact coordinates. To click by ref, use `gsd-browser click-ref` instead.

```bash theme={null}
gsd-browser click <selector> [flags]
gsd-browser click --x <n> --y <n> [flags]
```

<ParamField path="selector" type="string">
  CSS selector of the element to click. Omit when clicking by coordinates.
</ParamField>

<ParamField query="--x" type="number">
  Horizontal coordinate in CSS pixels. Must be used with `--y`.
</ParamField>

<ParamField query="--y" type="number">
  Vertical coordinate in CSS pixels. Must be used with `--x`.
</ParamField>

**Examples**

```bash theme={null}
# Click a button by CSS selector
gsd-browser click "#submit-btn"

# Click at exact coordinates
gsd-browser click --x 640 --y 360
```

***

## `gsd-browser click-ref`

Click an element identified by its snapshot ref. Prefer this over `click` when you have a fresh snapshot — refs encode element identity more precisely than CSS selectors.

```bash theme={null}
gsd-browser click-ref <ref>
```

<ParamField path="ref" type="string" required>
  A versioned ref string in `@vN:eM` format, as returned by `gsd-browser snapshot`.
</ParamField>

**Example**

```bash theme={null}
gsd-browser snapshot
gsd-browser click-ref @v1:e2
```

***

## `gsd-browser type`

Type text into an input element. By default the text is filled atomically; use `--slowly` when you need realistic keystroke-by-keystroke input (e.g. to trigger autocomplete handlers).

```bash theme={null}
gsd-browser type <selector> <text> [flags]
```

<ParamField path="selector" type="string" required>
  CSS selector of the target input, textarea, or content-editable element.
</ParamField>

<ParamField path="text" type="string" required>
  The text to type into the element.
</ParamField>

<ParamField query="--slowly" type="flag">
  Type character-by-character with realistic delays between keystrokes. Useful for triggering autocomplete, search suggestions, or other keystroke-driven event listeners.
</ParamField>

<ParamField query="--clear-first" type="flag">
  Clear any existing value in the field before typing the new text.
</ParamField>

<ParamField query="--submit" type="flag">
  Press Enter after typing to submit the field or form.
</ParamField>

**Examples**

```bash theme={null}
# Type an email address into the email input
gsd-browser type "input[name=email]" "hello@example.com"

# Clear a pre-filled field and type a new value
gsd-browser type "#search" "gsd-browser docs" --clear-first

# Type slowly to trigger autocomplete, then submit
gsd-browser type "#city-input" "San Fra" --slowly --submit
```

***

## `gsd-browser fill-ref`

Type text into an element identified by its snapshot ref.

```bash theme={null}
gsd-browser fill-ref <ref> <text> [flags]
```

<ParamField path="ref" type="string" required>
  A versioned ref string in `@vN:eM` format, as returned by `gsd-browser snapshot`.
</ParamField>

<ParamField path="text" type="string" required>
  The text to type into the element.
</ParamField>

<ParamField query="--clear-first" type="flag">
  Clear any existing value before typing.
</ParamField>

<ParamField query="--submit" type="flag">
  Press Enter after typing.
</ParamField>

<ParamField query="--slowly" type="flag">
  Type character-by-character instead of atomically filling the field.
</ParamField>

**Example**

```bash theme={null}
gsd-browser snapshot
gsd-browser fill-ref @v1:e1 "user@example.com"
```

***

## `gsd-browser press`

Dispatch a keyboard event for a single key or a key combination. Use key names from the DOM `KeyboardEvent.key` spec, joined by `+` for modifiers.

```bash theme={null}
gsd-browser press <key>
```

<ParamField path="key" type="string" required>
  Key name or combination. Examples: `Enter`, `Escape`, `Tab`, `ArrowDown`, `Meta+A`, `Control+C`, `Shift+Tab`.
</ParamField>

**Examples**

```bash theme={null}
# Press Enter to submit
gsd-browser press Enter

# Select all text
gsd-browser press Meta+A

# Dismiss a modal with Escape
gsd-browser press Escape

# Move focus to the next form field
gsd-browser press Tab
```

***

## `gsd-browser hover`

Move the mouse pointer over an element to trigger hover states, tooltips, or dropdown menus that only appear on mouse-over.

```bash theme={null}
gsd-browser hover <selector>
```

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

**Example**

```bash theme={null}
# Reveal a dropdown menu
gsd-browser hover "#nav-products"
gsd-browser snapshot --mode navigation
# Now snapshot the revealed menu items
```

***

## `gsd-browser scroll`

Scroll the page up or down. Use `--direction` to choose the direction and `--amount` to control how far.

```bash theme={null}
gsd-browser scroll --direction <direction> [--amount <px>]
```

<ParamField query="--direction" type="string" required>
  Scroll direction: `up` or `down`.
</ParamField>

<ParamField query="--amount" type="number">
  Number of pixels to scroll. Defaults to `300`.
</ParamField>

**Examples**

```bash theme={null}
# Scroll the page down 300 px (default)
gsd-browser scroll --direction down

# Scroll the page up 500 px
gsd-browser scroll --direction up --amount 500
```

***

## `gsd-browser select-option`

Select an option from a `<select>` dropdown element by matching its label text or value attribute.

```bash theme={null}
gsd-browser select-option <selector> <option>
```

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

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

**Example**

```bash theme={null}
# Select "Canada" from a country dropdown
gsd-browser select-option "select[name=country]" "Canada"

# Select by value attribute
gsd-browser select-option "#plan-select" "pro"
```

***

## `gsd-browser set-checked`

Set the checked state of a checkbox or radio button. Pass `--checked` to check the element; omit it to uncheck.

```bash theme={null}
gsd-browser set-checked <selector> [--checked]
```

<ParamField path="selector" type="string" required>
  CSS selector of the checkbox or radio `<input>` element.
</ParamField>

<ParamField query="--checked" type="flag">
  Set the element to the checked state. Omit this flag to uncheck the element.
</ParamField>

**Examples**

```bash theme={null}
# Check the "Accept terms" checkbox
gsd-browser set-checked "#accept-terms" --checked

# Uncheck a newsletter opt-in box
gsd-browser set-checked "input[name=newsletter]"
```

***

## `gsd-browser drag`

Drag an element from a source to a target using either CSS selectors or explicit coordinates. The drag movement is interpolated across several steps to produce realistic pointer events.

```bash theme={null}
gsd-browser drag <source> <target> [flags]
gsd-browser drag --from-x <n> --from-y <n> --to-x <n> --to-y <n> [flags]
```

<ParamField path="source" type="string">
  CSS selector of the element to drag from.
</ParamField>

<ParamField path="target" type="string">
  CSS selector of the element to drop onto.
</ParamField>

<ParamField query="--from-x" type="number">
  Starting X coordinate in CSS pixels (coordinate-based mode).
</ParamField>

<ParamField query="--from-y" type="number">
  Starting Y coordinate in CSS pixels (coordinate-based mode).
</ParamField>

<ParamField query="--to-x" type="number">
  Ending X coordinate in CSS pixels (coordinate-based mode).
</ParamField>

<ParamField query="--to-y" type="number">
  Ending Y coordinate in CSS pixels (coordinate-based mode).
</ParamField>

<ParamField query="--steps" type="number">
  Number of interpolation steps between start and end positions. Higher values produce smoother motion. Defaults to `10`.
</ParamField>

<ParamField query="--button" type="string">
  Mouse button held during the drag: `left` (default), `right`, or `middle`.
</ParamField>

**Examples**

```bash theme={null}
# Drag a card from one list column to another
gsd-browser drag ".card:first-child" ".column-done"

# Drag by coordinates for pixel-precise control
gsd-browser drag --from-x 100 --from-y 200 --to-x 400 --to-y 200

# Increase steps for smoother animation-sensitive drag
gsd-browser drag "#slider-thumb" "#slider-end" --steps 30
```

***

## `gsd-browser upload-file`

Set one or more files on a `<input type="file">` element. Pass local file paths as space-separated positional arguments.

```bash theme={null}
gsd-browser upload-file <selector> <file> [<file> ...]
```

<ParamField path="selector" type="string" required>
  CSS selector of the `<input type="file">` element.
</ParamField>

<ParamField path="files" type="string[]" required>
  One or more local file paths to attach to the input.
</ParamField>

**Examples**

```bash theme={null}
# Upload a single file
gsd-browser upload-file "input[type=file]" /home/user/report.pdf

# Upload multiple files at once
gsd-browser upload-file "#file-picker" ./photo1.jpg ./photo2.jpg ./photo3.jpg
```

***

## `gsd-browser act-instruction`

Execute a short natural-language instruction by planning concrete primitive steps (click, type, select-option, set-checked, drag, scroll) against the live page and dispatching them. Use this when the action isn't one of the built-in `gsd-browser act` semantic patterns — for example, "choose California from State" or "click the second Delete button".

```bash theme={null}
gsd-browser act-instruction <instruction> [flags]
```

<ParamField path="instruction" type="string" required>
  Short action-oriented instruction, e.g. `"click Continue"`, `"enter 'alice@example.com' into Email"`, or `"choose California from State"`.
</ParamField>

<ParamField query="--dry-run" type="flag">
  Return the inferred action plan without executing it. Useful for inspecting which element the planner selected before committing to the action.
</ParamField>

<ParamField query="--scope" type="string">
  CSS selector that constrains planning to a specific form, dialog, panel, or page region. Use this when the page has repeated controls.
</ParamField>

<ParamField query="--min-confidence" type="number">
  Block execution when the inferred plan confidence is below this threshold (between `0` and `1`). Fails closed on ambiguous instructions instead of guessing.
</ParamField>

<ParamField query="--max-steps" type="number">
  Cap on primitive steps the instruction may execute. Defaults to a small bounded sequence.
</ParamField>

**Examples**

```bash theme={null}
# Type into a labelled input by name
gsd-browser act-instruction "enter 'alice@example.com' into Email"

# Constrain planning to a specific form and require high confidence
gsd-browser act-instruction "click Continue" --scope "#signup-form" --min-confidence 0.7

# Inspect the plan before executing
gsd-browser act-instruction "click the second Delete button" --scope "#row-42" --dry-run

# Pick a value from a dropdown
gsd-browser act-instruction "choose California from State"
```

<Tip>
  Prefer ref-based commands like `click-ref` and `fill-ref` when you have a fresh snapshot and need pixel-precise control. Use `act-instruction` for higher-level intent when the exact selector is unstable or unknown.
</Tip>

***

## `gsd-browser set-viewport`

Resize the browser viewport using a named preset or exact pixel dimensions. Use this to test responsive layouts or simulate device screen sizes.

```bash theme={null}
gsd-browser set-viewport [flags]
```

<ParamField query="--preset" type="string">
  A named viewport preset:

  | Preset    | Dimensions  |
  | --------- | ----------- |
  | `mobile`  | 390 × 844   |
  | `tablet`  | 768 × 1024  |
  | `desktop` | 1280 × 800  |
  | `wide`    | 1920 × 1080 |
</ParamField>

<ParamField query="--width" type="number">
  Viewport width in pixels. Use with `--height` for custom dimensions.
</ParamField>

<ParamField query="--height" type="number">
  Viewport height in pixels. Use with `--width` for custom dimensions.
</ParamField>

**Examples**

```bash theme={null}
# Switch to a mobile viewport
gsd-browser set-viewport --preset mobile

# Set a custom resolution for a specific test
gsd-browser set-viewport --width 1440 --height 900

# Switch to wide desktop and take a screenshot
gsd-browser set-viewport --preset wide
gsd-browser screenshot --full-page --output wide-layout.png
```