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