51 lines
2.9 KiB
Markdown
51 lines
2.9 KiB
Markdown
---
|
||
summary: 'Move, resize, and focus windows via peekaboo window'
|
||
read_when:
|
||
- 'wrangling app windows before issuing UI interactions'
|
||
- 'needing JSON receipts for close/minimize/maximize/focus actions'
|
||
---
|
||
|
||
# `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
|
||
```bash
|
||
# 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.
|