Skip to content

Latest commit

 

History

History
48 lines (39 loc) · 3.09 KB

app.md

File metadata and controls

48 lines (39 loc) · 3.09 KB
summary read_when
Control macOS apps via peekaboo app
launching/quitting/focusing apps as part of an automation flow
auditing running apps or force cycling foreground focus

peekaboo app

app bundles every app-management primitive Peekaboo exposes: launching, quitting, hiding, relaunching, switching focus, and listing processes. Each subcommand works directly with NSWorkspace/AX data so it shares the same view of the system as the rest of the CLI.

Subcommands

Name Purpose Key flags
launch Start an app by name/path/bundle ID, optionally opening documents. --bundle-id, `--open <path
quit Quit one app or all regular apps (with optional exclusions). --app <name>, --pid, --all, --except "Finder,Terminal", --force.
relaunch Quit + relaunch the same app in one step. Positional <app>, --wait <seconds> between quit/launch, --force, --wait-until-ready.
hide / unhide Toggle app visibility. Accept the same targeting flags as launch/quit.
switch Activate a specific app (--to) or cycle Cmd+Tab style (--cycle). `--to <name
list Enumerate running apps. --include-hidden, --include-background.

Implementation notes

  • Launch resolves bundle IDs first, then friendly names (searching /Applications, /System/Applications, ~/Applications, etc.), and finally absolute paths. --open can be repeated to pass multiple documents/URLs to the launched app.
  • Quit mode supports --all plus --except, automatically ignoring core system processes (Finder, Dock, SystemUIServer, WindowServer). When quits fail, the command prints hints about unsaved changes and suggests --force.
  • Hide/unhide uses NSRunningApplication.hide() / .unhide() and surfaces JSON output with per-app success data.
  • switch --cycle synthesizes Cmd+Tab events using CGEvent so it behaves like the real keyboard shortcut; switch --to activates the exact PID resolved via AX.
  • switch --verify confirms the requested app is frontmost after activation (only supported with --to).
  • relaunch polls for termination (up to 5 s), waits the requested interval, then launches via bundle ID or bundle path and optionally waits for isFinishedLaunching before reporting success.

Examples

# Launch Xcode with a project and keep it backgrounded
polter peekaboo -- app launch "Xcode" --open ~/Projects/Peekaboo.xcodeproj --no-focus

# Quit everything but Finder and Terminal
polter peekaboo -- app quit --all --except "Finder,Terminal"

# Cycle to the next app exactly once
polter peekaboo -- app switch --cycle

# Switch and verify the app is frontmost
polter peekaboo -- app switch --to Safari --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-output or --verbose to surface detailed errors.