blog/content/posts/dead-simple-notifications-with-pushover.md

+++
date = '2026-05-29T16:25:23-05:00'
draft = false
title = 'Dead Simple Notifications With Pushover and shell'
+++

## What is Pushover?

[Pushover](https://pushover.net/) 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](https://pushover.net/apps) for popular applications. Pushover
provides a simple [HTTP API](https://pushover.net/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](https://pushover.net/settings/upgrade). The mobile application
itself has a 30-day free trial, after which there is a one-time
[fee](https://pushover.net/pricing) of $5 per platform.

## Getting Set Up

To get started the user will need a Pushover account. Head to
[pushover.net](https://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.

```bash
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](https://support.pushover.net/i44-example-code-and-pushover-libraries)
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.

```bash
#!/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`:

```sh
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:

```sh
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:

```bash
#!/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.