List all accessibility surfaces available for an application. Surfaces include windows, menus, menu bars, sheets, popovers, and alerts.
Usage
agent-desktop list-surfaces [OPTIONS]
Parameters
Filter to a specific application by name. If omitted, uses the focused application.
Response
Process ID of the application.
Array of accessibility surfaces.
Surface type: window, menu, menubar, sheet, popover, alert.
Surface title (e.g., window title or menu name). May be empty for some surfaces.
Number of items in the surface (for menus and menu bars).
Examples
List surfaces for Finder
agent-desktop list-surfaces --app Finder
{
"version": "1.0",
"ok": true,
"command": "list-surfaces",
"data": {
"pid": 1234,
"surfaces": [
{
"type": "window",
"title": "Documents"
},
{
"type": "window",
"title": "Downloads"
},
{
"type": "menubar",
"item_count": 8
}
]
}
}
agent-desktop list-surfaces --app TextEdit
{
"version": "1.0",
"ok": true,
"command": "list-surfaces",
"data": {
"pid": 5678,
"surfaces": [
{
"type": "window",
"title": "Untitled"
},
{
"type": "menubar",
"item_count": 7
},
{
"type": "menu",
"title": "File",
"item_count": 12
}
]
}
}
List surfaces with sheet
agent-desktop list-surfaces --app Safari
{
"version": "1.0",
"ok": true,
"command": "list-surfaces",
"data": {
"pid": 9012,
"surfaces": [
{
"type": "window",
"title": "Google"
},
{
"type": "menubar",
"item_count": 9
},
{
"type": "sheet",
"title": "Save As"
}
]
}
}
List surfaces with alert
agent-desktop list-surfaces --app Notes
{
"version": "1.0",
"ok": true,
"command": "list-surfaces",
"data": {
"pid": 3456,
"surfaces": [
{
"type": "window",
"title": "Notes"
},
{
"type": "menubar",
"item_count": 6
},
{
"type": "alert",
"title": "Delete Note?"
}
]
}
}
Focused app with no additional surfaces
agent-desktop list-surfaces
{
"version": "1.0",
"ok": true,
"command": "list-surfaces",
"data": {
"pid": 7890,
"surfaces": [
{
"type": "window",
"title": "Terminal"
},
{
"type": "menubar",
"item_count": 7
}
]
}
}
Error Cases
Application not found
{
"version": "1.0",
"ok": false,
"command": "list-surfaces",
"error": {
"code": "APP_NOT_FOUND",
"message": "No windows found for app 'InvalidApp'"
}
}
Permission denied
{
"version": "1.0",
"ok": false,
"command": "list-surfaces",
"error": {
"code": "PERM_DENIED",
"message": "Accessibility permission not granted",
"suggestion": "Open System Settings > Privacy & Security > Accessibility and add your terminal"
}
}
Surface Types
window
Standard application windows. Most apps have at least one window.
The application’s menu bar. Present for all GUI apps on macOS.
An open menu (e.g., File, Edit, View). Only present when a menu is actively displayed.
sheet
A modal sheet attached to a window (e.g., Save dialog, Preferences).
popover
A popover window (e.g., color picker, formatting options).
alert
A modal alert or confirmation dialog.
Notes
- The list is dynamic and reflects the current state of the application.
- Menus only appear in the list when they are actively open.
- Sheets, popovers, and alerts are temporary and disappear after dismissal.
- Use the
--surface flag with the snapshot command to capture a specific surface.
- The
item_count field is only populated for menus and menu bars.
- Not all surfaces have a
title (e.g., some popovers).
Use Cases
Check if any surfaces have type: "menu" to determine if a menu is currently open.
Wait for dialogs
Poll list-surfaces to detect when a sheet or alert appears.
Use list-surfaces to find an open menu, then snapshot --surface menu to capture its contents.
Verify window count
Count surfaces with type: "window" to ensure the expected number of windows are open.
See Also
