Skip to main content
Version Requirement: CLI automation is only available in Badgeify version 1.9.2 and later. Please update to the latest version if you’re running an older release.

​
Badgeify Command-Line Interface

Badgeify bundles a lightweight CLI inside the desktop binary so automations can inspect notification badges without launching the UI. Run the Badgeify executable with one of the supported subcommands to query state and exit immediately. 
Badgeify <subcommand> [options]
The process prints a JSON payload to stdout and terminates with exit code 0 on success and 1 on error. Errors are emitted on stderr.

​
Prerequisites

  • Badgeify must already be configured with the apps or groups you want to monitor.
  • macOS accessibility permissions are required. If the CLI fails with a NO_PERMISSIONS error, grant access via System Settings → Privacy & Security → Accessibility and relaunch Badgeify once to register the permission.

​
Discover Available IDs

Use list to retrieve the apps and groups that can be queried. Each entry exposes an id, type, name, and whether it is currently enabled. 
$ Badgeify list
{"success":true,"data":[{"id":"com.apple.Mail","type":"app","name":"Mail"}]}
The id field becomes the argument for other subcommands.
Free tier note: Without an active license, only the first three configured items are returned.

​
Query Unread Status

Fetch the current menubar badge for a specific app or group with status and the --id flag. 
$ Badgeify status --id com.apple.Mail
{"success":true,"data":{"type":"app","id":"com.apple.Mail","name":"Mail","enabled":true,"isRunning":true,"shown":true,"unread":5,"statusLabel":"5"}}
Important fields:
  • unread – integer badge count (0 when cleared).
  • statusLabel – raw menubar badge text (mirrors what macOS reports).
  • shown – whether the item is currently visible in the Badgeify tray.
  • isRunning – whether the underlying app is running right now.
If the requested ID is unknown, the CLI returns a NOT_FOUND error: 
$ Badgeify status --id unknown
{"success":false,"error":{"code":"NOT_FOUND","message":"No app or group found with ID: unknown","details":{"requestedId":"unknown"}}}
Free tier note: For unlicensed users, status is limited to the first three configured items and returns a FORBIDDEN error for others.

​
Exit Codes

  • 0 – Command succeeded and JSON was printed to stdout.
  • 1 – Validation, permission, or runtime error; JSON error payload printed to stderr.

​
Automation Tips

  • The CLI sets the BADGEIFY_CLI_MODE=1 environment variable while running. You can detect this flag inside scripts if needed.
  • Poll Badgeify status --id <bundle> on an interval to react to badge changes from tools like Hammerspoon.
  • Parse stdout as JSON to inspect unread. For shell scripting, tools such as jq make it easy:
    • Badgeify status --id com.apple.Mail | jq '.data.unread'

​
Troubleshooting

SymptomLikely CauseResolution
NO_PERMISSIONS errorAccessibility access not grantedOpen System Settings, add Badgeify to Accessibility, relaunch the app
CLI exits without printing JSONCommand failed before reaching the handlerRe-run with Badgeify --help to verify syntax; check stderr for the error payload
Badge count differs from macOS dockThe monitored app may suppress menubar badges or accessibility APIsConfirm the badge appears in the macOS menu bar. Badgeify reports exactly what macOS exposes

​
Getting Help

If the CLI output looks incorrect or you encounter issues not covered here, please capture the command output and email support@badgeify.app so we can investigate.
⌘I