Skip to main content

​
Syntax

agent-desktop mouse-down --xy <x,y> [--button <button>]

​
Description

Presses a mouse button at absolute screen coordinates without releasing it. Useful for manual drag operations or holding buttons for extended actions.
You must call mouse-up to release the button. Failing to do so may leave the mouse in a pressed state.

​
Parameters

​
--xy
string
required
Absolute screen coordinates in format x,y (e.g., 500,300). Coordinates are measured from the top-left corner of the primary display.
​
--button
string
default:"left"
Mouse button to press:
  • left - Primary button
  • right - Secondary button
  • middle - Middle button (scroll wheel)

​
Examples

​
Press left button

agent-desktop mouse-down --xy 500,300
Response: 
{
  "version": "1.0",
  "ok": true,
  "command": "mouse-down",
  "data": {
    "pressed": true,
    "x": 500.0,
    "y": 300.0
  }
}

​
Press right button

agent-desktop mouse-down --xy 500,300 --button right

​
Manual drag sequence

# Press at start point
agent-desktop mouse-down --xy 100,200

# Move to end point
agent-desktop mouse-move --xy 400,200

# Release button
agent-desktop mouse-up --xy 400,200
This sequence manually constructs a drag operation with full control over timing and path.

​
Press and hold for context menu

agent-desktop mouse-down --xy 500,300
agent-desktop wait 800
agent-desktop mouse-up --xy 500,300
Some applications show context menus on long press.

​
Use Cases

  • Implement custom drag-and-drop with intermediate steps
  • Hold button while moving cursor along specific path
  • Simulate long-press gestures for context menus
  • Multi-button sequences (hold one button, click another)
  • Fine-grained control over mouse state timing
  • mouse-up - Release the pressed button (required pair)
  • mouse-move - Move cursor while button is held
  • mouse-click - Complete press-release cycle
  • drag - High-level drag operation
  • wait - Pause between press and release

Build docs developers (and LLMs) love

Get started for freeTalk to us