@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.
string
Focus the snapshot on a subset of elements. Accepted values:
string
Scope the snapshot to a specific region of the page using a CSS selector.
number
Maximum number of elements to include. Defaults to
40. Increase this on complex single-page apps.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.
string
required
A versioned ref string in
@vN:eM format, as returned by gsd-browser snapshot.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.
string
CSS selector of the element to click. Omit when clicking by coordinates.
number
Horizontal coordinate in CSS pixels. Must be used with
--y.number
Vertical coordinate in CSS pixels. Must be used with
--x.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.
string
required
A versioned ref string in
@vN:eM format, as returned by gsd-browser snapshot.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).
string
required
CSS selector of the target input, textarea, or content-editable element.
string
required
The text to type into the element.
flag
Type character-by-character with realistic delays between keystrokes. Useful for triggering autocomplete, search suggestions, or other keystroke-driven event listeners.
flag
Clear any existing value in the field before typing the new text.
flag
Press Enter after typing to submit the field or form.
gsd-browser fill-ref
Type text into an element identified by its snapshot ref.
string
required
A versioned ref string in
@vN:eM format, as returned by gsd-browser snapshot.string
required
The text to type into the element.
flag
Clear any existing value before typing.
flag
Press Enter after typing.
flag
Type character-by-character instead of atomically filling the field.
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.
string
required
Key name or combination. Examples:
Enter, Escape, Tab, ArrowDown, Meta+A, Control+C, Shift+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.
string
required
CSS selector of the element to hover over.
gsd-browser scroll
Scroll the page up or down. Use --direction to choose the direction and --amount to control how far.
string
required
Scroll direction:
up or down.number
Number of pixels to scroll. Defaults to
300.gsd-browser select-option
Select an option from a <select> dropdown element by matching its label text or value attribute.
string
required
CSS selector of the
<select> element.string
required
The option label (visible text) or value attribute to select.
gsd-browser set-checked
Set the checked state of a checkbox or radio button. Pass --checked to check the element; omit it to uncheck.
string
required
CSS selector of the checkbox or radio
<input> element.flag
Set the element to the checked state. Omit this flag to uncheck the element.
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.
string
CSS selector of the element to drag from.
string
CSS selector of the element to drop onto.
number
Starting X coordinate in CSS pixels (coordinate-based mode).
number
Starting Y coordinate in CSS pixels (coordinate-based mode).
number
Ending X coordinate in CSS pixels (coordinate-based mode).
number
Ending Y coordinate in CSS pixels (coordinate-based mode).
number
Number of interpolation steps between start and end positions. Higher values produce smoother motion. Defaults to
10.string
Mouse button held during the drag:
left (default), right, or middle.gsd-browser upload-file
Set one or more files on a <input type="file"> element. Pass local file paths as space-separated positional arguments.
string
required
CSS selector of the
<input type="file"> element.string[]
required
One or more local file paths to attach to the input.
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”.
string
required
Short action-oriented instruction, e.g.
"click Continue", "enter 'alice@example.com' into Email", or "choose California from State".flag
Return the inferred action plan without executing it. Useful for inspecting which element the planner selected before committing to the action.
string
CSS selector that constrains planning to a specific form, dialog, panel, or page region. Use this when the page has repeated controls.
number
Block execution when the inferred plan confidence is below this threshold (between
0 and 1). Fails closed on ambiguous instructions instead of guessing.number
Cap on primitive steps the instruction may execute. Defaults to a small bounded sequence.
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.
string
A named viewport preset:
number
Viewport width in pixels. Use with
--height for custom dimensions.number
Viewport height in pixels. Use with
--width for custom dimensions.