peekaboo dialog

dialog wraps DialogService so you can programmatically inspect, click, type into, dismiss, or drive file dialogs without re-running see. Pass a target (--app/--pid plus optional --window-id/--window-title/--window-index) whenever possible so Peekaboo can focus the right app/window before interacting.

#Subcommands

#Implementation notes

• dialog subcommands share the same targeting flags as other interaction commands (--app/--pid plus --window-id/--window-title/--window-index) and use the same focus helpers before interacting.
• Button clicks and text entry route through services.dialogs helpers, which return dictionaries describing what happened; JSON output exposes those details verbatim (button, field, text_length, etc.).
• dialog input accepts either a field label (--field) or an index; when neither is provided it targets the first text field. --clear issues a Cmd+A/Delete before typing.
• dialog file can both navigate to a path and fill the filename field, then clicks the action button you specify (--select Save, --select Open, etc.). Leave --path blank to simply confirm the current directory.
• dialog file defaults to clicking the dialog’s OKButton when --select is omitted (or set to default). Prefer this when you don’t want to guess whether the button is labeled “Save”, “Open”, “Choose”, etc.
• --ensure-expanded expands the dialog (Show Details) before applying --path. If no PathTextField is present, Peekaboo falls back to the standard “Go to Folder…” shortcut to reliably land in the requested directory.
• For save-like actions (resolved by the actual clicked button title), dialog file verifies that the saved file appears on disk (5s timeout). On success it returns saved_path and saved_path_verified=true. If you provided --path + --name, Peekaboo also enforces that the file landed in the requested directory (symlinks like /tmp → /private/tmp are normalized).
• JSON output includes additional provenance for debugging without screenshots, including dialog_identifier, found_via, button_identifier, saved_path_found_via, and path_navigation_method (e.g. path_textfield_typed+fallback_go_to_folder).
• dialog list is invaluable before scripting a dialog: it prints button titles, placeholders, and static text so you can pick stable labels instead of guessing.

#Examples

# Click "Don't Save" on a TextEdit sheet
peekaboo dialog click --button "Don't Save" --app TextEdit

# Enter credentials into a password prompt
peekaboo dialog input --text hunter2 --field "Password" --clear --app Safari

# Choose a file in an open panel and confirm
peekaboo dialog file --path ~/Downloads --name report.pdf --select Open

# Save a file and verify the resulting path exists
peekaboo dialog file --path /tmp --name poem.rtf --select Save --app TextEdit --json

# Click the default action (OKButton) and include dialog provenance in JSON output
peekaboo dialog file --path ~/Downloads --name report.pdf --ensure-expanded --app TextEdit --json

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