Skip to content

Latest commit

 

History

History
45 lines (37 loc) · 2.75 KB

scroll.md

File metadata and controls

45 lines (37 loc) · 2.75 KB
summary read_when
Simulate mouse wheel movement via peekaboo scroll
panning long views or tables without dragging the scrollbar
needing scroll telemetry (direction, ticks) for automation logs

peekaboo scroll

scroll emulates trackpad/mouse-wheel input in any direction. You can scroll at the pointer position or aim at a previously captured element ID so the automation service scrolls that region even if the cursor is elsewhere.

Key options

Flag Description
`--direction up down
--amount <ticks> Number of scroll “ticks” (default 3). Smooth mode multiplies this internally.
--on <element-id> Scroll relative to a Peekaboo element from the current/most recent snapshot.
--snapshot <id> Override the snapshot used to resolve --on. Omit when you want to scroll wherever the pointer is.
--delay <ms> Milliseconds between ticks (default 2).
--smooth Use smaller increments (3 micro ticks per requested tick) for finer movement.
Target flags --app <name>, --pid <pid>, --window-id <id>, --window-title <title>, --window-index <n> — focus a specific app/window before scrolling. (--window-title/--window-index require --app or --pid; --window-id does not.)
Focus flags FocusCommandOptions control Space switching + retries.

Implementation notes

  • If you pass --on without a snapshot, the command automatically looks up services.snapshots.getMostRecentSnapshot() so you rarely need to wire IDs manually.
  • Focus is handled via ensureFocused; supplying a target helps the command recover when the scrollable view lives in a background Space.
  • JSON output reports the actual point that was scrolled: for element targets it resolves the bounds midpoint, otherwise it samples the current cursor location via CGEvent(source:nil)?.location.
  • ScrollRequest is handed directly to AutomationServiceBridge.scroll, so the CLI benefits from the same smooth/step semantics the agent runtime sees.

Examples

# Scroll down five ticks wherever the pointer currently sits
polter peekaboo -- scroll --direction down --amount 5

# Scroll the element labeled "table_orders" using the latest snapshot
polter peekaboo -- scroll --direction up --amount 2 --on table_orders

# Smooth horizontal pan inside Keynote without switching Spaces
polter peekaboo -- scroll --direction right --smooth --app Keynote --space-switch

Troubleshooting

  • Verify Screen Recording + Accessibility permissions (peekaboo permissions status).
  • Confirm your target (app/window/selector) with peekaboo list/peekaboo see before rerunning.
  • Re-run with --json-output or --verbose to surface detailed errors.