Command-line tool

The gregor command sends alerts from shell scripts, cron jobs, and CI. It is a single file with no dependencies, for Linux, macOS, and Windows. It does what you would otherwise write by hand around curl:

• Encrypts alerts for channels that require end-to-end encryption.
• Runs a command and sends an alert only if it fails, with the exit code and the last lines of output.
• Retries network errors and rate limits without sending the same alert twice.

It sends what you give it unchanged. The server checks every limit, and the command prints its error when one is exceeded.

The command only sends: it cannot read your inbox or change channels. Download links will appear on the home page when it is released. Put the file on your PATH.

Configure

The command reads the URLs and key from environment variables, so they stay out of your shell history and process list:

Variable	Used for
SEND_URL	The channel’s send URL. Override it with -url.
CHANNEL_KEY	The channel key, ck1:…. When it is set, every alert is encrypted. Or pass -key-file with a file that holds the key.
HEARTBEAT_URL	The heartbeat URL for gregor heartbeat.

export SEND_URL='https://<api-host>/v1/send/<token>'

Send an alert

gregor send "Build failed" "3 tests failed on main"

The first argument is the title and the second, optional, is the body. Use - as the body to read it from standard input:

df -h | gregor send -level high "Disk almost full" -

Flag	Request field
-level	level: urgent, high, normal (default), or silent
-link	url
-event, -subject, -fingerprint	event.type, event.subject, event.fingerprint; see repeated events
-thread	thread_key
-ack	require_ack
-receipt	receipt
-payload	payload, a JSON object; not allowed with encryption
-idempotency-key	idempotency_key; generated if omitted

The command prints the alert ID, and the receipt ID when there is one. Add -json to print the full response, or -q to print nothing.

Encrypted alerts

Set CHANNEL_KEY to the key you copied from the app, and send as usual:

export CHANNEL_KEY='ck1:<channel_id>:<key_version>:<key>'
gregor send -event backup.failed -subject host:nas "Backup failed" "nas: exit code 2"

The title, body, and link are encrypted on your machine. The level, event, and thread stay readable by the server, so do not put secrets in them. -payload is rejected with a key, because the payload would be sent in plaintext. After you rotate the key, update CHANNEL_KEY.

Alert when a command fails

gregor run runs a command, passes its output through, and exits with its exit code. If the command fails, it sends one alert:

gregor run -- /usr/local/bin/backup.sh --full

Put the command after --. The alert defaults to:

Field	Default
Title	backup.sh failed on <host>; change it with -title
Body	The exit code, how long the command ran, and its last 20 lines of output, at most 800 characters; change the line count with -lines
Level	high
Event	Type command.failed, subject host:<host>:<command>, so repeated failures update one alert

All the send flags work with run. A command that cannot start sends an alert and exits with code 127.

To also catch jobs that never run at all, report a heartbeat when the command succeeds:

30 2 * * * gregor run -heartbeat "$HEARTBEAT_URL" -- /usr/local/bin/backup.sh

Report a heartbeat

gregor heartbeat

It uses HEARTBEAT_URL, or a URL given as the argument. Heartbeats are not available on encrypted channels.

Retries and errors

Network errors, server errors, and 429 responses are retried up to 3 times; set the number with -retries and the timeout of each attempt with -timeout (default 10s). A 429 waits for its Retry-After, up to a minute. Every retry sends the same idempotency key, so an alert is never created twice.

Other errors are not retried. The command prints the error code and what to do, and exits with code 1. Errors name only the host, never the token in the URL.

Exit code	Meaning
0	Sent.
1	Not sent: an error, a limit, or a missing setting.
2	Wrong flags or arguments.
Other	With run: the command’s own exit code.