`peekaboo window`

window gives you programmatic control over macOS windows. Every subcommand accepts WindowIdentificationOptions (--app, --pid, --window-id, --window-title, --window-index) so you can pinpoint the exact window before acting. Output is mirrored in JSON and text for easy scripting.

#Subcommands

Name	Purpose	Key options
`close` / `minimize` / `maximize`	Perform the respective window chrome action.	Standard window-identification flags.
`focus`	Bring the window forward, optionally hopping Spaces or moving it to the current Space.	Adds `FocusCommandOptions` plus `--verify` to confirm focus.
`move`	Move the window to new coordinates.	`-x <int>` / `-y <int>` specify the new origin.
`resize`	Adjust width/height while keeping the origin.	`-w <int>` / `--height <int>`.
`set-bounds`	Set both origin and size in one go.	`--x`, `--y`, `--width`, `--height`.
`list`	Shortcut for `list windows` scoped to a single app.	Same targeting flags; outputs the `list windows` payload.

#Implementation notes

Every action validates that at least an app, PID, or window ID is supplied; optional --window-title and --window-index disambiguate when multiple windows exist.
All geometry-changing commands re-fetch window info after acting (when possible) and stuff the updated bounds into the JSON payload so automated tests can assert the final rectangle.
focus routes through WindowServiceBridge.focusWindow and honors the global focus flags (--space-switch to jump Spaces, --bring-to-current-space to move the window instead, etc.). It logs debug output when focus fails so agents know to fall back.
focus --verify checks the frontmost app (and window ID when available) before returning success.
When window list runs, it simply calls the same helper as peekaboo list windows but saves you from retyping the longer command.

#Examples

# Move Finder’s 2nd window to (100,100)
peekaboo window move --app Finder --window-index 1 -x 100 -y 100

# Close a specific window deterministically (window_id from `peekaboo window list --json`)
peekaboo window close --window-id 12345

# Resize Safari’s frontmost window to 1200x800
peekaboo window resize --app Safari -w 1200 --height 800

# Focus Terminal even if it lives on another Space
peekaboo window focus --app Terminal --space-switch

# Focus and verify the frontmost window
peekaboo window focus --app Terminal --verify

#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.