Skip to main content
Click an action button (e.g., “Reply”, “Open”, “Snooze”) on a notification in the Notification Center.

​
Usage

agent-desktop notification-action <INDEX> <ACTION>

​
Parameters

​
INDEX
number
required
1-based notification index from list-notifications. Must be >= 1.Note: While list-notifications returns 0-based indices, this command accepts 1-based indices for user convenience.
agent-desktop notification-action 1 Reply
​
ACTION
string
required
Name of the action button to click. Must match one of the action names in the notification’s actions array from list-notifications.Common action names:
  • Reply
  • Open
  • Snooze
  • Mark as Read
  • Dismiss
agent-desktop notification-action 1 Open

​
Response

​
action
string
required
The name of the action that was clicked

​
Examples

​
Click Reply Action

# First, list notifications to see available actions
agent-desktop list-notifications

# Click the Reply button on the first notification
agent-desktop notification-action 1 Reply

{
  "version": "1.0",
  "ok": true,
  "command": "notification-action",
  "data": {
    "action": "Reply"
  }
}

​
Open Notification

agent-desktop notification-action 2 Open

{
  "version": "1.0",
  "ok": true,
  "command": "notification-action",
  "data": {
    "action": "Open"
  }
}

​
Workflow

1

List notifications

Run list-notifications to see notifications and their available actions:
agent-desktop list-notifications
Example output:
{
  "notifications": [
    {
      "index": 0,
      "app_name": "Messages",
      "title": "New message from John",
      "actions": ["Reply", "Open"]
    }
  ]
}
2

Note the index and action

Identify the notification index (add 1 for 1-based) and the action name you want to trigger.
3

Click the action

Use the index + 1 and action name:
agent-desktop notification-action 1 Reply

​
Use Cases

Reply to Messages notifications directly from the CLI:
agent-desktop list-notifications --app Messages
agent-desktop notification-action 1 Reply
# This opens the Messages reply field
Open the app associated with a notification:
agent-desktop notification-action 1 Open
This brings the app to the foreground and navigates to the relevant content.
Snooze Calendar or Reminders notifications:
agent-desktop notification-action 1 Snooze
Automatically respond to specific notifications:
# In a script
NOTIF=$(agent-desktop list-notifications --text "deployment complete" | jq -r '.data.notifications[0]')
INDEX=$(echo $NOTIF | jq -r '.index + 1')
agent-desktop notification-action $INDEX Open

​
Action Availability

Not all notifications have action buttons. Check the actions array in the notification object from list-notifications: 
agent-desktop list-notifications | jq '.data.notifications[] | select(.actions | length > 0)'
Common apps with action buttons:
  • Messages: Reply, Open
  • Mail: Reply, Delete, Mark as Read
  • Calendar: Snooze, Open
  • Slack: Reply, Open, Mark as Read
  • Reminders: Complete, Snooze

​
Error Handling

Common error codes:
  • ELEMENT_NOT_FOUND: Index out of range or notification already dismissed
  • ACTION_NOT_SUPPORTED: Action name not found in notification’s actions array
  • INVALID_ARGS: Index is 0 or negative, or action name is empty
  • ACTION_FAILED: The action button exists but clicking it failed
{
  "version": "1.0",
  "ok": false,
  "command": "notification-action",
  "error": {
    "code": "ACTION_NOT_SUPPORTED",
    "message": "Action 'Delete' not available on this notification",
    "suggestion": "Run 'list-notifications' to see available actions for this notification"
  }
}

​
Notes

  • The command uses 1-based indexing for user convenience
  • Action names are case-sensitive and must match exactly
  • After clicking an action, the notification may be dismissed automatically (depends on the app)
  • Some actions (like “Open”) will bring the source app to the foreground
  • The action is performed via macOS accessibility APIs, so accessibility permission is required

Build docs developers (and LLMs) love

Get started for freeTalk to us