Skip to content

A bash alert when a script fails: policy first, then the function

Which events deserve a buzz, and where a shell alert stops and a page monitor starts.

3 min read

A bash alert when a script fails beats a green dashboard nobody opens, because it arrives on the device you already check. The setup is small: a token in the environment, one curl call in a function, and a policy about which events deserve a buzz.

Start with the policy, not the code

Decide first what deserves a notification, because that decision outlives any tool.

Event Notify? Why
Backup job exits non-zero Yes The failure is invisible otherwise
Disk above 90% Yes The next write may fail
Deploy step fails Yes Someone is waiting on it
Backup job succeeds No Daily success is noise
A page you watch changes Depends Better handled by a page monitor

That last row is the boundary worth stating plainly. A shell alert knows what your script knows. If the thing you care about is a public web page changing, a curl loop comparing HTML will fire on every timestamp and stop the moment your machine sleeps. A page monitor such as AyeWatch watches public pages, topics and social accounts from its own infrastructure and sends push, feed, email, Slack, Discord or webhooks, with paid plans from $9 a month. Use the shell for your own jobs, the monitor for other people's pages.

The function

alert() {
  local msg="$1"
  curl --fail --silent --show-error "https://ayeping.com/@you" \
       -H "Authorization: Bearer ${AYEPING_TOKEN}" \
       --data "$msg" > /dev/null
}

Place alert "rsync failed on $(hostname)" on the failure branch. The -f option is not optional in practice: it converts an HTTP error into a failing exit status, and without it a revoked token produces the same quiet success as a delivered message.

Making the message useful

Three elements answer the first question a person asks at an awkward hour: which machine, which job, what went wrong.

  • db-2: pg_dump exit 1
  • nas-1: backup failed, disk 98%
  • build 4182: migrate step failed

A message of just "error" teaches the recipient to open the app instead of the log, which is the opposite of the intent.

Protecting the credential

Keep the secret in the process environment or a unit file rather than inline in the script. Issue a separate credential per host on the Tokens page, so decommissioning a server means deleting its own key and nothing else. If one is pasted somewhere public by mistake, pause it (it then answers 403 token_paused) and mint a replacement.

Retries and rate limits

A wrapper that retries should send an Idempotency-Key header so a repeat returns the first ping id rather than delivering twice. And each token has an hourly ceiling between 1 and 3,600 requests, 60 by default, so a check that runs every minute sits exactly on the limit.

Cost, as of November 2026

The Free plan gives 5 pings and 3 tokens with no card. Hobby runs $8 monthly or $49 annually with 120,000 pings and 25 tokens. Pro costs $20 monthly or $120 annually with 1,200,000 pings and 100 tokens. Unused pings do not carry over, so a failure-only policy stretches a small plan a long way.

FAQ

Should a bash alert also go to email?

If a missed alert has a cost, yes. Send the same event to a second channel and treat the phone as the fast one.

Can AyeWatch replace the shell alert?

They watch different things. AyeWatch watches public pages and topics. A shell alert reports what a script on your own machine discovered.

How do I test the failure branch?

Force it: point the script at a missing path and run it. If the phone stays quiet, check curl's exit code before suspecting the token.

FAQ

Should a bash alert also go to email?

If a missed alert has a cost, yes. Send the same event to a second channel and treat the phone as the fast one.

Can AyeWatch replace the shell alert?

They watch different things. AyeWatch watches public pages and topics. A shell alert reports what a script on your own machine discovered.

How do I test the failure branch?

Force it: point the script at a missing path and run it. If the phone stays quiet, check curl's exit code before suspecting the token.

Originally published on claudegpt.si