Wrap a job with the pingstack command

pingstack run wraps a scheduled job and reports it to a heartbeat check: a successful run, a failure with its exit code and the end of its output, and how long the run took. It replaces the curl line at the end of a job.

pingstack run -- /opt/jobs/backup.sh

The job’s output passes through unchanged and pingstack run exits with the job’s own exit code, so cron, systemd and Task Scheduler see what they did before. The command is free and open source: pingstack-io/pingstack-ping on GitHub.

Install

macOS with Homebrew:

brew install pingstack-io/tap/pingstack

macOS or Linux, install script:

curl -fsSL https://github.com/pingstack-io/pingstack-ping/releases/latest/download/install.sh | sh

The script downloads the build for your machine from the latest release, checks it against the release’s checksums, and installs it to /usr/local/bin, or ~/.local/bin when /usr/local/bin isn’t writable.

Windows, or any system by hand: download the archive for your system from the latest release and put pingstack.exe (or pingstack) on your PATH.

Check it works with pingstack version.

Use it

The command reads the ping URL from the PINGSTACK_PING_URL environment variable. Keep the URL in a file only the job’s user can read, as the crontab and systemd recipes show, rather than in the crontab or a script in version control.

Cron. Load the file, then run the job through pingstack run. Cron’s PATH is short, so use the full path to pingstack (which pingstack shows it):

0 2 * * * set -a; . "$HOME/.pingstack-backup"; /usr/local/bin/pingstack run -- /opt/jobs/backup.sh

systemd. Point the service at the environment file and wrap ExecStart:

[Service]
Type=oneshot
EnvironmentFile=/etc/pingstack/backup.env
ExecStart=/usr/local/bin/pingstack run -- /opt/jobs/backup.sh

Windows Task Scheduler. Set PINGSTACK_PING_URL for the task’s user, then make the task’s action run pingstack.exe with the arguments run -- powershell.exe -File C:\jobs\backup.ps1.

What it sends

When	What Pingstack receives	Result in Pingstack
The job starts	A start signal	No status change; the run’s time starts
The job exits 0	A heartbeat with `exit_code=0`	Location up; the run time is shown in recent results
The job exits non-zero, is killed, or can’t start	A failure with the exit code and the last 100 lines of output	Location failed; on a one-location check, an incident opens at once

On success no output is sent, so routine logs stay on the machine. A job killed by a signal is reported with exit code 128 plus the signal number, as shells report it, and a command that can’t be found as 127.

A report that can’t be delivered is retried on network errors, rate limits and server errors, then printed as a warning; it never changes the exit code. If PINGSTACK_PING_URL is missing or isn’t a Pingstack address, the job still runs and nothing is sent.

Options

Flag	Default	Effect
`--url`	`$PINGSTACK_PING_URL`	The ping URL. The environment variable keeps it out of process lists and shell history.
`--value`	none	A number checked against the check’s thresholds.
`--value-from-output`	off	Send the last number the job printed as the value.
`--tail`	`100`	Lines of output sent with a failure, at most 10 KB. `0` sends none.
`--no-start`	off	Skip the start signal, so no run time is recorded.
`--retries`	`5`	Retries for each report.
`--timeout`	`10s`	Time to wait for each request.
`--quiet`	off	Print nothing of its own; the job’s output still passes through.

pingstack ping sends a single report for scripts that report on their own: add --fail or --start, and optionally --exit-code and --message. It exits 1 when the report couldn’t be delivered.

pingstack ping --fail --exit-code 3 --message "export found no rows"

Security

The command sends reports only to https:// addresses on pingstack.io and never prints the ping URL, including in error messages. It’s a single binary built from its public repository, with checksums published for every release.