scroll-to

​

Overview

​

Syntax

agent-desktop scroll-to <ref>

​

Parameters

​

Response

{
  "version": "1.0",
  "ok": true,
  "command": "scroll-to",
  "data": {
    "action": "scroll_to",
    "ref_id": "@e20"
  }
}

​

Response Fields

​

AX-First Strategy

1. Uses kAXScrollToVisibleAction on the element via accessibility
2. Calculates element position and scrolls parent container
3. Falls back to mouse wheel events if AX fails
4. Verifies element bounds are within visible area

​

Usage Examples

​

Scroll List Item Into View

agent-desktop snapshot --app Finder -i
agent-desktop find --role "row" --name "file_deep_in_list.txt"
agent-desktop scroll-to @e45
agent-desktop click @e45

​

Scroll and Interact

# Element may not be visible in initial snapshot
agent-desktop snapshot --app Safari -i

# Scroll to footer button
agent-desktop scroll-to @e30

# Now it's visible and clickable
agent-desktop click @e30

​

Scroll to Form Field

agent-desktop snapshot --app "System Settings" -i
agent-desktop scroll-to @e18  # Scroll to "Submit" button
agent-desktop click @e18

​

Ensure Visibility Before Action

# Always scroll-to before clicking elements in long lists
agent-desktop scroll-to @e25
agent-desktop wait 200
agent-desktop click @e25

​

When to Use Scroll-To

• Element is in snapshot but may be off-screen
• You need to interact with an element that’s not visible
• Working with long lists or scrollable containers
• Ensuring element visibility before click/type

• Element is already visible
• Clicking elements in current viewport
• Element doesn’t have a parent scroll area

​

Scroll-To vs Scroll

# scroll-to: "Show me element @e20"
agent-desktop scroll-to @e20

# scroll: "Move down 5 units"
agent-desktop scroll @e1 --direction down --amount 5

​

Common Use Cases

• Long Lists: Scroll to items deep in file/folder lists
• Form Submissions: Scroll to submit button at bottom
• Search Results: Scroll to specific search result
• Tree Navigation: Reveal nested tree items
• Settings Panels: Scroll to specific setting in long panel

​

Element Visibility

• Is within the visible bounds of its scroll area
• May be at top, middle, or bottom of viewport (platform-dependent)
• Is ready for interaction (click, type, etc.)
• May have different coordinates than before

​

Error Cases

​

Verifying Visibility

# Scroll to element
agent-desktop scroll-to @e20

# Check if visible
agent-desktop is @e20 visible
# Returns: {"ok": true, "data": true}

# Or check bounds
agent-desktop get @e20 bounds
# Returns: {"x": ..., "y": ..., "width": ..., "height": ...}

​

Scroll-To + Snapshot Pattern

# Initial snapshot may show element but it's off-screen
agent-desktop snapshot -i

# Scroll to element
agent-desktop scroll-to @e25

# Take new snapshot to see updated positions
agent-desktop snapshot -i

# Now interact with element
agent-desktop click @e25

​

Performance

• Faster than multiple directional scroll commands
• Single operation to reach target
• Platform-optimized scrolling
• May trigger smooth scroll animation

​

Automatic Scrolling

agent-desktop scroll-to @e15
agent-desktop click @e15

​

Nested Scrolling

# Scroll outer container
agent-desktop scroll-to @e10

# Then scroll inner container
agent-desktop scroll-to @e25

​

Notes

• Element must exist in current snapshot (have a ref)
• Scrolls parent container, not the element itself
• Final position may vary (top/middle/bottom of viewport)
• Some apps animate scroll; consider adding wait
• Always snapshot after scroll-to to capture new state
• Use is @ref visible to verify visibility
• More efficient than searching with multiple scroll commands
• Does not change focus or selection