---
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` 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` 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
```bash
# List every status item with indices
peekaboo menubar list

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

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

# Click the third item regardless of name and capture JSON output
peekaboo menubar click --index 3 --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.
