DOCSEARCHbyAlgolia
Submit Docs

alerter

repository·master·Indexed 22 days ago

https://github.com/vjeantet/alerter

A Swift-based command-line tool for macOS that sends interactive notifications. It supports reply alerts with text input and action alerts with custom buttons or dropdowns, outputting user interactions to the shell as text or JSON.

Tokens
1.3K
Snippets
3
Records
6
Agent score
29%

What's inside alerter

  1. How Reply Alerts and Actions Alerts work

    master

    Alerter supports two primary interaction models for macOS notifications:

    1. Reply Alert: Displays a notification with a "Reply" button that opens a text input field. Use the --reply TEXT option to set placeholder text in the input field.
    2. Actions Alert: Displays a notification with one or more action buttons. Use the --actions VALUE1,VALUE2 option to provide buttons. If multiple values are provided, a dropdown is displayed, which can be customized using --dropdown-label.

    Note: --reply and --actions cannot be combined.

  2. Install Alerter

    master

    Alerter can be installed via Homebrew (recommended), MacPorts, manual download, or by building from source.

    Homebrew (recommended)

    brew install vjeantet/tap/alerter

    MacPorts

    sudo port install alerter

    Manual

    1. Download the zipped precompiled binary from the releases section.
    2. Extract the binary.
    3. Place it in a directory listed in your $PATH (e.g. /usr/local/bin).

    Build from source

    git clone https://github.com/vjeantet/alerter.git
cd alerter
swift build -c release
# Binary is at .build/release/alerter
    brew install vjeantet/tap/alerter

  3. Use Alerter to send notifications

    master

    Alerter is a CLI tool that sends macOS notifications. It can read the message body from the --message flag or from standard input (piped data). The program exits when the user interacts with the alert or dismisses it, printing the result to stdout.

    Basic Usage

    # Using a message flag
./alerter --message "Hello World"

# Using piped data
echo 'Piped Message Data!' | alerter --sound default
    echo 'Piped Message Data!' | alerter --sound default

  4. Handle alert interaction results in shell scripts

    master

    When an alert is interacted with, Alerter prints the result to stdout. You can capture this output in a shell script to drive logic based on user input.

    Common return values include:

    • The specific action name (e.g., YES, NO, MAYBE)
    • @TIMEOUT: The alert was automatically closed due to the --timeout setting.
    • @CLOSED: The user clicked the default close button.
    • @CONTENTCLICKED: The user clicked the notification content.
    • @ACTIONCLICKED: The user clicked the default action button.

    Example Scripting Pattern:

    ANSWER="$(./alerter --message 'Start now ?' --close-label No --actions 'YES,MAYBE,one more action' --timeout 10)"
case $ANSWER in
    "@TIMEOUT") echo "Timeout man, sorry" ;;
    "@CLOSED") echo "You clicked on the default alert' close button" ;;
    "@CONTENTCLICKED") echo "You clicked the alert's content !" ;;
    "@ACTIONCLICKED") echo "You clicked the alert default action button" ;;
    "MAYBE") echo "Action MAYBE" ;;
    "NO") echo "Action NO" ;;
    "YES") echo "Action YES" ;;
    **) echo "? --> $ANSWER" ;;
esac
    ANSWER="$(./alerter --message 'Start now ?' --close-label No --actions 'YES,MAYBE,one more action' --timeout 10)"
case $ANSWER in
    "@TIMEOUT") echo "Timeout man, sorry" ;;
    "@CLOSED") echo "You clicked on the default alert' close button" ;;
    "@CONTENTCLICKED") echo "You clicked the alert's content !" ;;
    "@ACTIONCLICKED") echo "You clicked the alert default action button" ;;
    "MAYBE") echo "Action MAYBE" ;;
    "NO") echo "Action NO" ;;
    "YES") echo "Action YES" ;;
    **) echo "? --> $ANSWER" ;;
esac

  5. Reference: Alerter CLI Options

    master

    At a minimum, you must specify either --message, --remove, or --list.

    OptionDescription
    --message VALUE[required] The message body. If omitted, data piped to stdin is used.
    --reply TEXTDisplays a reply-type alert. TEXT is placeholder text. Cannot combine with --actions.
    --actions VALUE1,VALUE2Available action buttons. Multiple values trigger a dropdown. Cannot combine with --reply.
    --dropdown-label VALUELabel for the actions dropdown.
    --close-label VALUECustom label for the "Close" button.
    --title VALUENotification title. Defaults to 'Terminal'.
    --subtitle VALUENotification subtitle.
    --delay NUMBERDelay delivery by NUMBER seconds. Cannot combine with --at.
    --at TIMEDeliver at HH:mm (next occurrence) or yyyy-MM-dd HH:mm (future date). Cannot combine with --delay.
    --timeout NUMBERAutomatically close alert after NUMBER seconds.
    --sound NAMEPlay a sound (e.g., default).
    --jsonOutput result as a JSON object.
    --group IDGroup notifications. Only one notification per ID is shown at a time.
    --remove ID[required] Removes notification with specified ID. Use ALL to remove all.
    --list ID[required] Lists details of ID group. Use ALL for all active notifications. Returns JSON array.
    --sender IDImpersonate an application (e.g., com.apple.Terminal).
    --app-icon PATHPath/URL for app icon. (Uses private API).
    --content-image PATHPath/URL for image inside notification. (Uses private API).
    --ignore-dndIgnore Do Not Disturb. (Uses private API).

  6. Run the Alerter CLI

    master
    The alerter command-line interface is the primary entrypoint for triggering alerts. It is managed by AlerterCommand.main(). When running the CLI, it handles system signals (SIGTERM and SIGINT) by calling NotificationManager.shared.bye() to ensure a clean shutdown of the notification system before exiting.