Skip to content

menubar.md

Latest commit

 

History

History
51 lines (41 loc) · 3.13 KB

menubar.md

File metadata and controls

51 lines (41 loc) · 3.13 KB
summary Work with macOS status items via peekaboo menubar
read_when
clicking Wi-Fi/Bluetooth/battery icons from automation flows
enumerating third-party status items with indices for later use

peekaboo menubar

menubar is a lightweight helper for macOS status items (a.k.a. menu bar extras). It talks directly to MenuServiceBridge so you can list every icon with its index or click one by title/index. Use the menu command for traditional application menus; this command is strictly for the right-hand side of the menu bar.

Actions

Positional action Description
list Prints every visible status item with its index. --json-output emits the same data plus bundle IDs and AX identifiers.
click Clicks an item by name (case-insensitive fuzzy match) or via --index <n>.

Key options

Flag Description
[itemName] Optional positional argument passed to click.
--index <n> Target by numeric index (matches the ordering from menubar list).
--verify After clicking, confirm a popover owned by the same PID appears, or that focus moved to the owning app/window (fallback OCR). OCR requires the popover text to include the target title/owner name and anchors verification to the clicked item’s X position when available.
Global flags --json-output returns structured payloads; --verbose adds descriptions when listing.

Implementation notes

  • The command name is menubar (no hyphen). Commander enforces list/click as the only valid actions.
  • Listing uses MenuServiceBridge.listMenuBarItems, and verbose mode prints extra diagnostics (owner name, hidden state). JSON mode always includes the raw title, bundle ID, owner name, identifier, visibility, and description.
  • Clicking resolves either --index or item text (case-insensitive). When an item isn’t found, text mode prints troubleshooting hints; JSON mode surfaces MENU_ITEM_NOT_FOUND.
  • --verify waits briefly for a popover owned by the same PID, checks for a focused-window change for the owning app, then falls back to any visible owner window (layer 0). OCR verification is on by default (set PEEKABOO_MENUBAR_OCR_VERIFY=0 to disable) and now requires the popover text to include the target title/owner; AX menu checks remain opt-in via PEEKABOO_MENUBAR_AX_VERIFY=1 (OCR requires Screen Recording permission).
  • Coordinate data (if available) is recorded in the click result so you can correlate where on screen the interaction happened.

Examples

# List every status item with indices
polter peekaboo -- menubar list

# Click the Wi-Fi icon by name
polter peekaboo -- menubar click "Wi-Fi"

# Click and verify the popover opened
polter peekaboo -- menubar click "Wi-Fi" --verify

# Click the third item regardless of name and capture JSON output
polter peekaboo -- menubar click --index 3 --json-output

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.