menubar

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. Listing is read-only and stays in the background. Clicking opens global menu bar UI and therefore requires explicit --foreground consent. Use the menu command for traditional application menus; this command is strictly for the right-hand side of the menu bar.

Subcommands

Subcommand	Description
list	Prints every visible status item with its index. --json 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).
--foreground	Required for click; permits Peekaboo to open global status-item UI and interrupt the current foreground workflow.
--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 returns structured payloads; --verbose adds descriptions when listing.

Implementation notes

• The command name is menubar (no hyphen). list and click are real Commander subcommands.
• 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.
• click refuses before status-item lookup unless --foreground is present. Missing names and stale indices then fail before dispatch as MENU_ITEM_NOT_FOUND with effect: refused, retry_safe: true, and mutation_dispatched: false in JSON.
• Clicking resolves either --index or item text (case-insensitive). Name-based targets remain name-based at dispatch so a status-item reorder cannot redirect the click to a different index.
• --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.