| summary |
read_when |
| Automate macOS Dock interactions via peekaboo dock |
| launching/closing apps through Dock affordances |
| toggling Dock visibility or iterating over Dock items in scripts |
|
peekaboo dock
dock exposes Dock-specific helpers so you don’t have to rely on brittle coordinate clicks. It leverages DockServiceBridge, which uses AX to locate Dock items, right-click menus, and visibility toggles.
Subcommands
| Name |
Purpose |
Key options |
launch <app> |
Left-click a Dock icon to launch/activate it. |
Positional app title as shown in the Dock; add --verify to wait for the app to be running. |
right-click |
Open a Dock item’s context menu (and optionally pick a menu item). |
--app <Dock title> plus optional --select "Keep in Dock", --select "New Window", etc. |
hide / show |
Toggle Dock visibility (same as System Settings ➝ Dock & Menu Bar). |
No options. |
list |
Enumerate Dock items, their bundle IDs, and whether they’re running/pinned. |
--json prints structured info (titles, kind, position). |
Implementation notes
- Item resolution is AX-based, so names match what VoiceOver would read (case-sensitive). Launching returns success even when the app is already running; the Dock is still clicked to bring it forward.
launch --verify polls for the app to appear in the running-application list before returning success.right-click first finds the item, then triggers the context menu, then optionally selects --select <title>. If you omit --select, it just opens the menu (useful if you want to inspect it with see).- Hide/show operations call the Dock service and return JSON/text acknowledgements; they don’t fiddle with defaults commands, so they’re instantaneous and reversible.
- Errors coming from
DockServiceBridge (item not found, Dock unavailable) are mapped to structured error codes when --json is active, which helps CI detect missing icons.
Examples
# Launch Safari directly from the Dock
peekaboo dock launch Safari
# Launch and verify the app is running
peekaboo dock launch Safari --verify
# Right-click Finder and choose "New Window"
peekaboo dock right-click --app Finder --select "New Window"
# Hide the Dock before recording a video
peekaboo dock hide
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.
