Dead Simple Notifications With Pushover and shell

What is Pushover?

Pushover is a notification service that makes it easy to send real-time push notifications to the user’s phone from scripts and applications. Users can wrap the service in a few lines of shell and get real-time notifications for automated tasks. Some examples include docker container health checks, zpool status reports, and the outcome of shell commands.

The service has native applications for iOS and Android, and a browser-based client for desktop users. There is also a growing list of plugins for popular applications. Pushover provides a simple HTTP API. Used in combination with the mobile application, users can build simple but effective notification systems.

Cost and Limitations

The API allows up to 10,000 messages per month at no additional cost. Once that limit is reached, blocks of additional capacity can be purchased. The mobile application itself has a 30-day free trial, after which there is a one-time fee of $5 per platform.

Getting Set Up

To get started the user will need a Pushover account. Head to pushover.net and register. The user key is displayed in the dashboard after registration and identifies where notifications will be delivered. Install the mobile application and log in to start receiving notifications on the phone.

Next the user needs to create an application. In the Pushover dashboard, click “Create an Application/API Token”. Give it a name like “server-scripts” and submit the form. Pushover will generate an API token for that application.

The user will need both the user key and the API token to send notifications. Keep them somewhere safe.

Sending the First Notification

The simplest way to send a Pushover notification is with curl. This is a good way to verify the credentials are working before integrating notifications into scripts.

curl -s \
  --form-string "token=YOUR_API_TOKEN" \
  --form-string "user=YOUR_USER_KEY" \
  --form-string "message=hello world" \
  https://api.pushover.net/1/messages.json

Replace YOUR_API_TOKEN and YOUR_USER_KEY with the values from the Pushover dashboard. If everything is configured correctly, a notification will appear on the phone within seconds.

Pushover’s API supports a number of additional parameters, including message title, priority, and sound. See the Pushover example code page for examples in other languages.

Custom Notification Script

Rather than including the full curl command in every script, it can be wrapped in a shell script of its own. This gives a reusable command that can be called from any other script on the system.

#!/bin/sh

PUSHOVER_TOKEN="YOUR_API_TOKEN"
PUSHOVER_USER="YOUR_USER_KEY"

/usr/bin/curl -s \
  --form-string "token=$PUSHOVER_TOKEN" \
  --form-string "user=$PUSHOVER_USER" \
  --form-string "title=$1" \
  --form-string "message=$2" \
  https://api.pushover.net/1/messages.json

Save this as notify.sh and make it executable:

chmod +x notify.sh

Place it in a directory that is in the path of the user that will be running the notification scripts. On Linux ~/.local/bin is a common choice. On macOS /usr/local/bin is typical. Run echo $PATH to see what directories are currently in the user’s path.

With the script in place, sending a notification looks like this:

notify.sh "Testing notifications" "My first notification!"

Keep this script private and never commit it to a public repository. It contains the user’s Pushover credentials.

A Note on Sensitive Data

The API token and user key should be considered sensitive information. For a script that lives only on the user’s own machine and is never shared, storing them directly in the script is acceptable. If the user plans to share the script or commit it to a repository, use environment variables instead. Set them in a private file like ~/.pushover:

export PUSHOVER_TOKEN="your-token"
export PUSHOVER_USER="your-user-key"

Source that file in the shell profile so the variables are available to scripts:

source ~/.pushover

Then remove the hardcoded values from the script and reference the variables directly. The script is then safe to share publicly.

Practical Example

Call notify.sh at the end of any script to confirm it ran. Here it is used with a simple backup:

#!/bin/sh

rsync -a /home/$USER/ /mnt/backup/

if [ $? -eq 0 ]; then
  notify.sh "Backup" "Backup completed successfully"
else
  notify.sh "Backup" "Backup failed"
fi

Conclusion

With a Pushover account and a small shell script, the user has a notification system that works from anywhere a shell command can be run. Adding a notification to an existing script is a simple process. This makes it easy to stay informed about what is happening on the systems without having to check manually.