backupctl reference

backupctl wraps a backup command: it pings /start, runs the command, verifies the result, then pings /success or /fail. One static binary, zero non-stdlib dependencies.

backupctl run --url <base|ping url> [--key <key>] [checks...] -- <command...>

--url accepts a ping base (https://backpulse.aniicrite.dev, --key required) or a full ping URL (.../ping/<key>[/start|/success|/fail]). BACKPULSE_URL and BACKPULSE_PING_KEY are the flag defaults, so cron lines stay short.

Adapters

Adapter	Verifies
(none)	exit code matches --expect-exit (default 0)
restic	newest snapshot in the repo is within --max-age
pgdump	file checks below, plus custom-format magic for -Fc dumps
rclone	exit code plus an independent check of --remote
file checks (--path)	file exists, mtime within --max-age, size above --min-size, gzip magic for .gz

Flags

Flag	Meaning
--url	ping base or full ping URL (or BACKPULSE_URL)
--key	ping key when --url is a base (or BACKPULSE_PING_KEY)
--adapter	restic, pgdump, rclone, or empty for exit-code only
--path	artifact to verify (file checks)
--max-age	max acceptable artifact/snapshot age, e.g. 26h
--min-size	minimum artifact bytes
--restic-repo	repo override instead of the environment
--remote	remote path for the rclone adapter
--expect-exit	accepted command exit code (default 0)

Exit codes

Code	Meaning
0	command behaved and every check passed (/success)
N	command exited N (≠ --expect-exit), pinged /fail
1	command was fine but a check failed, pinged /fail
2	usage error (bad url/key/adapter, missing command)