---
summary: 'Position the cursor via peekaboo move'
read_when:
  - 'hovering elements without clicking'
  - 'lining up the pointer before a screenshot or drag sequence'
---

# `peekaboo move`

`move` repositions the macOS cursor using coordinate targets, element IDs, fuzzy queries, or a simple “center of screen” flag. It’s useful for hover-driven menus, tooltips, or aligning the cursor before taking a screenshot.

## Key options
| Flag | Description |
| --- | --- |
| `[x,y]` | Optional positional coordinates (e.g., `540,320`). |
| `--coords <x,y>` | Coordinate target as an option (alias for the positional argument). |
| `--on <element-id>` | Jump to a Peekaboo element’s midpoint based on the latest snapshot. |
| `--id <element-id>` | Alias for `--on`. |
| `--to <query>` | Resolve an element by text/query using `waitForElement` (5 s timeout). |
| `--center` | Move to the main screen’s center (exclusive with other targets). |
| `--snapshot <id>` | Required when using `--on`/`--id`/`--to`; defaults to the most recent snapshot. |
| Target flags | `--app <name>`, `--pid <pid>`, `--window-id <id>`, `--window-title <title>`, `--window-index <n>` — focus a specific app/window before moving. (`--window-title`/`--window-index` require `--app` or `--pid`; `--window-id` does not.) |
| Focus flags | `FocusCommandOptions` control Space switching + retries. |
| `--smooth` | Animate the move over multiple steps (defaults to 500 ms, 20 steps). |
| `--duration <ms>` / `--steps <n>` | Override the smooth-move timing/step count; instant moves use duration `0` unless overridden. |
| `--profile <linear\|human>` | Select a movement profile. `human` enables eased arcs and micro-jitter with no extra tuning required. |

## Implementation notes
- Validation enforces exactly one target: coordinates (`[x,y]` or `--coords`), `--on`/`--id`, `--to`, or `--center`.
- Element-based moves reuse snapshot data via `services.snapshots.getDetectionResult`; query-based moves run `AutomationServiceBridge.waitForElement`, so they automatically wait up to 5 s for dynamic UIs.
- Smooth moves compute intermediate steps client-side and track the previous cursor location so the result payload can include the travel distance.
- `--profile human` automatically enables smooth movement, adapts duration/steps to travel distance, and adds natural jitter/overshoot. See `docs/human-mouse-move.md` for deeper guidance.
- JSON output reports `fromLocation`, `targetLocation`, `targetDescription`, total distance, and run time. Element/query targets also include `targetPoint` diagnostics with the original snapshot midpoint, final resolved point, snapshot ID, and moved-window adjustment status.

## Examples
```bash
# Instantly move to a coordinate
peekaboo move 1024,88
peekaboo move --coords 1024,88

# Human-style movement with one flag
peekaboo move 520,360 --profile human

# Hover the element with ID `menu_gear` using the latest snapshot
peekaboo move --on menu_gear --smooth

# Center the cursor on the main display before taking a screenshot
peekaboo move --center --duration 250 --steps 15
```

## 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` or `--verbose` to surface detailed errors.