Interaction Commands

Interaction commands allow you to interact with elements on a web page: clicking buttons, filling forms, selecting options, hovering over elements, scrolling, and more. These commands are the workhorses of web automation.

---

click

Clicks an element on the page.

Description

The click command simulates a mouse click on a specific element. This is the most commonly used interaction command, as most web interactions involve clicking buttons, links, or other elements.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the element to click. Format: css=..., xpath=..., or text=....
button	String	No	"left"	The mouse button to use. Options: left, right, middle.
click_count	Number	No	1	The number of clicks. Use 2 for double-click.
force	Boolean	No	false	Force the click even if the element is obscured by other elements.
iframe	String	No	""	The selector for the iframe containing the element.
position	Object	No	null	The position to click relative to the element. Format: {x: number, y: number}.
modifiers	Array	No	[]	Keyboard modifiers to hold during the click. Options: Alt, Control, Meta, Shift.
timeout	Number (ms)	No	5000	Maximum time to wait for the element to be clickable.

Example

{
  "command": "click",
  "params": {
    "selector": "css=button.submit",
    "button": "left",
    "click_count": 1
  }
}

Double-click example:

{
  "command": "click",
  "params": {
    "selector": "css=.product-card",
    "click_count": 2
  }
}

Right-click example:

{
  "command": "click",
  "params": {
    "selector": "css=.context-menu-target",
    "button": "right"
  }
}

Humanoid Behavior

When humanoid behavior is enabled (default), the click command:

1. Scrolls the element into view if needed.
2. Calculates the element’s center position with slight randomization.
3. Moves the mouse to the element using a Bezier curve path (simulating human movement).
4. Adds a random delay before clicking (simulating human hesitation).
5. Performs the click.
6. Adds a random delay after clicking.

The sensitivity level (low, medium, high) controls how much randomization is applied.

Tips

• Use force: true if the element is obscured by overlays or popups.
• Use position to click a specific part of an element (e.g., the right side of a button).
• Use modifiers to simulate keyboard shortcuts (e.g., Control + click to open in a new tab).

---

fill

Fills an input element with text.

Description

The fill command sets the value of an input element. This is faster than type because it sets the value directly rather than simulating keystrokes.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the input element.
value	String	Yes	—	The text to fill. Supports ${variable} substitution.
clear_before_fill	Boolean	No	true	Clear existing text before filling.
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "fill",
  "params": {
    "selector": "css=input[name='email']",
    "value": "user@example.com",
    "clear_before_fill": true
  }
}

With variable substitution:

{
  "command": "fill",
  "params": {
    "selector": "css=input[name='search']",
    "value": "${search_term}"
  }
}

Humanoid Behavior

When humanoid behavior is enabled, the fill command:

1. Scrolls the element into view.
2. Moves the mouse to the element using a Bezier curve.
3. Clicks the element to focus it.
4. Types the text character by character with random delays between keystrokes.

Tips

• Use fill for simple text input. Use type if you need to simulate keystrokes (e.g., for autocomplete).
• Set clear_before_fill: false if you want to append text to existing content.

---

type

Types text sequentially into an element, simulating real user keystrokes.

Description

The type command simulates typing text character by character, with optional delays between keystrokes. This is more realistic than fill and is useful for triggering autocomplete or other keyboard-driven interactions.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the input element.
text	String	Yes	—	The text to type. Supports ${variable} substitution.
delay	Number (ms)	No	0	Delay between keystrokes in milliseconds.
clear	Boolean	No	false	Clear existing text before typing.
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "type",
  "params": {
    "selector": "css=input[name='search']",
    "text": "wireless headphones",
    "delay": 100,
    "clear": true
  }
}

Humanoid Behavior

When humanoid behavior is enabled, the type command adds random delays between keystrokes on top of the specified delay parameter, making the typing even more human-like.

Tips

• Use type instead of fill when you need to trigger autocomplete or other keyboard-driven interactions.
• Set delay to a value between 50-200ms for realistic typing speed.
• Set clear: true if you want to clear existing text before typing.

---

press

Simulates a key press on an element.

Description

The press command simulates pressing a keyboard key on a specific element. This is useful for pressing Enter, Tab, Escape, or other special keys.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the element.
key	String	Yes	"Enter"	The key to press (e.g., Enter, Tab, Escape, ArrowDown).
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "press",
  "params": {
    "selector": "css=input[name='search']",
    "key": "Enter"
  }
}

Common Keys

Key	Description
Enter	Press the Enter key
Tab	Press the Tab key
Escape	Press the Escape key
ArrowUp, ArrowDown, ArrowLeft, ArrowRight	Arrow keys
Backspace	Press the Backspace key
Delete	Press the Delete key
PageUp, PageDown	Page navigation keys
Home, End	Home and End keys

Tips

• Use press after fill or type to submit a form (e.g., press Enter after filling a search box).
• Use Tab to navigate between form fields.
• Use Escape to close modals or popups.

---

keyboard

Simulates a keyboard action with optional delay.

Description

The keyboard command is similar to press but with an optional delay parameter. It simulates a keyboard action on a specific element.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the element.
key	String	Yes	"Enter"	The key to press.
delay	Number (ms)	No	0	Delay before the key press in milliseconds.
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "keyboard",
  "params": {
    "selector": "css=input[name='search']",
    "key": "Enter",
    "delay": 500
  }
}

Tips

• Use keyboard instead of press when you need a delay before the key press.
• Use delay to simulate human hesitation before pressing a key.

---

check

Checks a checkbox or radio button.

Description

The check command checks a checkbox or selects a radio button. If the element is already checked, the command does nothing.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the checkbox or radio button.
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "check",
  "params": {
    "selector": "css=input[name='agree_terms']"
  }
}

Humanoid Behavior

When humanoid behavior is enabled, the check command:

1. Scrolls the element into view.
2. Moves the mouse to the element using a Bezier curve.
3. Clicks the element to check it.

Tips

• Use check for checkboxes and radio buttons.
• If the element is already checked, the command does nothing (no error is thrown).

---

uncheck

Unchecks a checkbox.

Description

The uncheck command unchecks a checkbox. If the element is already unchecked, the command does nothing.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the checkbox.
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "uncheck",
  "params": {
    "selector": "css=input[name='newsletter']"
  }
}

Tips

• Use uncheck to uncheck checkboxes.
• If the element is already unchecked, the command does nothing (no error is thrown).

---

select_option

Selects an option in a dropdown (<select>) element.

Description

The select_option command selects an option in a dropdown (<select>) element. You can select by value, label, or index.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the <select> element.
value	String	Yes	—	The value of the option to select.
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "select_option",
  "params": {
    "selector": "css=select[name='country']",
    "value": "us"
  }
}

Humanoid Behavior

When humanoid behavior is enabled, the select_option command:

1. Scrolls the element into view.
2. Moves the mouse to the element using a Bezier curve.
3. Clicks the element to open the dropdown.
4. Selects the specified option.

Tips

• Use the value attribute of the <option> element, not the visible text.
• If you need to select by visible text, use text= selector format.

---

hover

Hovers the mouse over an element.

Description

The hover command moves the mouse over an element without clicking it. This is useful for triggering hover-based interactions like dropdown menus or tooltips.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the element.
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "hover",
  "params": {
    "selector": "css=.dropdown-menu-trigger"
  }
}

Humanoid Behavior

When humanoid behavior is enabled, the hover command:

1. Scrolls the element into view.
2. Moves the mouse to the element using a Bezier curve.
3. Adds a random delay to simulate human hesitation.

Tips

• Use hover to trigger dropdown menus or tooltips.
• Add a wait command after hover if you need to wait for the hover effect to complete.

---

focus

Focuses an element.

Description

The focus command gives keyboard focus to an element. This is useful for triggering focus-based interactions or preparing an element for keyboard input.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the element.
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "focus",
  "params": {
    "selector": "css=input[name='search']"
  }
}

Tips

• Use focus before press or keyboard to ensure the element has keyboard focus.
• Use focus to trigger focus-based interactions like autocomplete.

---

scroll

Performs advanced scrolling actions.

Description

The scroll command scrolls the page or a specific element. You can scroll to the bottom, top, or by a specific number of pixels.

Parameters

Parameter	Type	Required	Default	Description
selector	String	No	""	The selector for the element to scroll. Leave empty to scroll the window.
direction	String	No	"bottom"	The scroll direction. Options: bottom, top, by_pixels.
amount	Number	No	0	The number of pixels to scroll (for by_pixels direction).
smooth	Boolean	No	false	Use smooth scrolling animation.
delay	Number (ms)	No	1000	Delay after scrolling in milliseconds.
repeats	Number	No	1	The number of times to repeat the scroll.
iframe	String	No	""	The selector for the iframe containing the element.

Example

Scroll to the bottom of the page:

{
  "command": "scroll",
  "params": {
    "direction": "bottom",
    "smooth": true,
    "delay": 1000
  }
}

Scroll a specific element by pixels:

{
  "command": "scroll",
  "params": {
    "selector": "css=.scrollable-container",
    "direction": "by_pixels",
    "amount": 500,
    "repeats": 3
  }
}

Tips

• Use smooth: true for realistic scrolling animation.
• Use repeats to scroll multiple times (useful for infinite scroll).
• Use delay to wait for content to load after scrolling.

---

scroll_into_view

Scrolls an element into the viewport.

Description

The scroll_into_view command scrolls the page until a specific element is visible in the viewport. This is useful for interacting with elements that are below the fold.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the element.
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "scroll_into_view",
  "params": {
    "selector": "css=.load-more-button"
  }
}

Humanoid Behavior

When humanoid behavior is enabled, the scroll_into_view command uses smooth scrolling to bring the element into view.

Tips

• Use scroll_into_view before interacting with elements that are below the fold.
• Most interaction commands (click, fill, etc.) automatically scroll elements into view, so you may not need this command explicitly.

---

drag_to

Drags an element to a target element.

Description

The drag_to command simulates dragging an element from one location to another. This is useful for drag-and-drop interactions.

Parameters

Parameter	Type	Required	Default	Description
source_selector	String	Yes	—	The selector for the element to drag.
target_selector	String	Yes	—	The selector for the target element.
source_position	Object	No	null	The position to start dragging from, relative to the source element. Format: {x: number, y: number}.
target_position	Object	No	null	The position to drop at, relative to the target element. Format: {x: number, y: number}.
iframe	String	No	""	The selector for the iframe containing the elements.
timeout	Number (ms)	No	5000	Maximum time to wait for the elements.

Example

{
  "command": "drag_to",
  "params": {
    "source_selector": "css=.draggable-item",
    "target_selector": "css=.drop-zone"
  }
}

Tips

• Use source_position and target_position to control the exact drag start and drop positions.
• If the drag doesn’t work, try adding a wait command before the drag to ensure the elements are fully loaded.

---

select_text

Selects the text content of an element.

Description

The select_text command selects the text content of an element, similar to highlighting text with the mouse.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the element.
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "select_text",
  "params": {
    "selector": "css=.article-content"
  }
}

Tips

• Use select_text to select text for copying or other text-based operations.
• Use press with Control+C after select_text to copy the selected text.

---

set_input_files

Selects files for a file input element, preparing them for upload.

Description

The set_input_files command selects files for a file input element, preparing them for upload. This is useful for automating file upload forms.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the file input element.
paths	String	Yes	"file.txt"	The file path(s) to select. Multiple files can be specified as a comma-separated list.
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "set_input_files",
  "params": {
    "selector": "css=input[type='file']",
    "paths": "/path/to/file.pdf"
  }
}

Tips

• Use absolute file paths for reliability.
• Multiple files can be specified as a comma-separated list.
• The file must exist on the local file system.

---

dispatch_event

Triggers a specific DOM event on an element.

Description

The dispatch_event command triggers a specific DOM event on an element. This is useful for triggering custom events that are not covered by other interaction commands.

Parameters

Parameter	Type	Required	Default	Description
selector	String	Yes	—	The selector for the element.
event_type	String	Yes	—	The type of event to dispatch (e.g., mouseover, change, focus).
iframe	String	No	""	The selector for the iframe containing the element.
timeout	Number (ms)	No	5000	Maximum time to wait for the element.

Example

{
  "command": "dispatch_event",
  "params": {
    "selector": "css=.custom-component",
    "event_type": "change"
  }
}

Common Event Types

Event Type	Description
click	Mouse click event
mouseover	Mouse over event
mouseout	Mouse out event
change	Change event (for form elements)
focus	Focus event
blur	Blur event
input	Input event (for form elements)
submit	Form submit event

Tips

• Use dispatch_event for custom events that are not covered by other interaction commands.
• Use dispatch_event to trigger events that are not triggered by normal user interactions.