Reference

`peekaboo swipe`

Home GitHub Edit page

peekaboo swipe

swipe drives AutomationServiceBridge.swipe to move from one point to another over a fixed duration. You can describe the endpoints via element IDs (from see) or raw coordinates, which makes it flexible for both deterministic automation and exploratory scripts.

#Key options

FlagDescription
--from <id> / --from-coords x,ySource location (ID requires a valid snapshot).
--to <id> / --to-coords x,yDestination location (also supports IDs or literal coordinates).
--snapshot <id>Needed whenever you reference IDs so the command can look up bounds. Auto-resolves to the most recent snapshot if omitted.
Target flags--app <name>, --pid <pid>, --window-id <id>, --window-title <title>, --window-index <n> — focus a specific app/window before swiping. (--window-title/--window-index require --app or --pid; --window-id does not.)
Focus flagsFocusCommandOptions control Space switching + retries.
--duration <ms>Default 500 ms; controls how long the swipe lasts.
--steps <count>Number of intermediate points for smoothing (default 20).
--right-buttonCurrently rejected — the implementation throws a validation error because right-button drags are not yet wired up.
--profile <linear|human>Use human for gesture traces that look like real pointer motion.

#Implementation notes

  • The command validates that both ends are provided (mixing IDs and coordinates is fine) before doing any work.
  • Element lookups reuse the [waitForElement + bounds.midpoint] flow with a 5 s timeout, so swipes tolerate elements that pop in slightly late.
  • Coordinate parsing accepts "x,y" with optional whitespace; invalid strings result in immediate validation errors.
  • After issuing the swipe it waits ~0.1 s before reporting success to give AppKit time to settle (matching what integration tests expect).
  • JSON output surfaces both endpoints and the computed Euclidean distance. Element endpoints also include fromTargetPoint/toTargetPoint diagnostics with the original snapshot midpoint, final resolved point, snapshot ID, and moved-window adjustment status.
  • --profile human enables adaptive durations/steps plus jittery arcs; see docs/human-mouse-move.md for the generator’s behavior.

#Examples

# Swipe between two element IDs captured by `see`
peekaboo swipe --from card_1 --to card_2 --duration 650 --steps 30

# Drag from coordinates (x1,y1) to (x2,y2)
peekaboo swipe --from-coords 120,880 --to-coords 120,200

# Human-style swipe with adaptive easing
peekaboo swipe --from-coords 80,640 --to-coords 820,320 --profile human

# Mix coordinate → element drag using the most recent snapshot
peekaboo swipe --from-coords 400,400 --to drawer_toggle

#Troubleshooting

  • Verify Screen Recording + Accessibility permissions (peekaboo permissions status).
  • Confirm your target (app/window/selector) with peekaboo list/peekaboo see before rerunning.
  • If you see SNAPSHOT_NOT_FOUND, regenerate the snapshot with peekaboo see (or omit --snapshot to use the most recent one).
  • Re-run with --json or --verbose to surface detailed errors.