# checkpulse-run

`checkpulse-run` wraps a job so it reports to Checkpulse without any changes to the job itself. It:

1. sends `/start` with a new run ID,
2. runs the command, passing its output through,
3. sends the exit status with the command line, duration, and the last 4 KB of output,
4. exits with the command's own exit status.

If a ping fails, the wrapper prints a warning on stderr and retries, but never changes the job's exit status.

## Install

The shell version needs only `sh` and `curl`:

```sh
curl -fsSL https://checkpulse.foo/checkpulse-run.sh -o /usr/local/bin/checkpulse-run
chmod +x /usr/local/bin/checkpulse-run
```

Review the script before installing it; it is short.

## Use

```sh
checkpulse-run 'https://checkpulse.foo/ping/<token>' /usr/local/bin/backup.sh --full
```

Or set the URL in the environment:

```sh
CHECKPULSE_URL='https://checkpulse.foo/ping/<token>' checkpulse-run /usr/local/bin/backup.sh
```

The shell version merges the job's stderr into its stdout.

### In crontab

```text
0 2 * * * /usr/local/bin/checkpulse-run 'https://checkpulse.foo/ping/<token>' /usr/local/bin/backup.sh
```

### With systemd timers

```ini
[Service]
Type=oneshot
ExecStart=/usr/local/bin/checkpulse-run 'https://checkpulse.foo/ping/<token>' /usr/local/bin/backup.sh
```

### Slug URLs and automatic creation

Combine with slug URLs to monitor a job without creating the check first:

```sh
checkpulse-run "https://checkpulse.foo/ping/$PING_KEY/nightly-backup" /usr/local/bin/backup.sh
```

Set `CHECKPULSE_CREATE=1` to create the check on its first ping, with a daily schedule you can adjust later.

## The checkpulse binary

The `checkpulse` server binary includes the same wrapper as a subcommand, and is in the Checkpulse Docker image:

```sh
checkpulse run --url 'https://checkpulse.foo/ping/<token>' -- /usr/local/bin/backup.sh --full
checkpulse run --server https://checkpulse.foo --ping-key "$PING_KEY" --slug nightly-backup --create -- ./backup.sh
```

| Flag | Default | Meaning |
|---|---|---|
| `--url` | `$CHECKPULSE_URL` | Ping URL for the check. |
| `--server`, `--ping-key`, `--slug` | `$CHECKPULSE_SERVER`, `$CHECKPULSE_PING_KEY` | Build a slug URL instead. |
| `--create` | off | Create the check on first ping (slug URLs). |
| `--no-start` | off | Skip the start signal. |
| `--timeout` | `10s` | Timeout for each ping. |
| `--retries` | `3` | Retries for each ping. |

The binary keeps stdout and stderr separate. A command that cannot be found exits with 127 and reports a failure.