Shell Script Client

The bundled hellocron.sh client wraps the API calls so you don’t write curl by hand. The source lives in the public hellocron/cli repository on GitHub - audit it, star it, or open an issue there.

Installation

Download the latest client and put it on your PATH:

curl -fsSL https://hellocron.com/hellocron.sh -o /usr/local/bin/hellocron
chmod +x /usr/local/bin/hellocron

Optional: verify the download against the published checksum.

curl -fsSL https://hellocron.com/hellocron.sh.sha256
sha256sum /usr/local/bin/hellocron

Configure once with your ingest key, created in the panel under Settings and API keys:

hellocron configure                      # asks for the key, nothing else
hellocron configure --api-key ck_xxx     # or set it without prompting

That writes ~/.hellocron.conf with permissions 600:

api_key=ck_your_ingest_key
telemetry_enabled=true
default_project=

The API address is built into the client, so it is not part of the config. Point the client somewhere else only for a self-hosted or staging setup, with hellocron configure --advanced or an api_url= line in the config file.

A legacy JSON config at ~/.hellocron-config.json is still read when .hellocron.conf is absent.

Every ping reports the machine it came from. In a container, where the hostname is a random hex, pin it with a hostname= line in the config file or HELLOCRON_HOSTNAME.

Version and updates

The download URL always serves the latest client. Updates are on demand, not automatic.

hellocron version          # installed version and date
hellocron update --check   # check whether a newer version exists
hellocron update           # download, verify checksum, replace (keeps a .bak)

update pulls from the same URL, verifies the SHA-256 checksum, runs a syntax check, backs up the current file as .bak, then swaps it in. It needs curl, sha256sum and bash, and only updates over HTTPS.

Version history: client changelog.

Usage

hellocron ping <monitor-name> <status> [options]
hellocron run <monitor-name> <command...>
hellocron discover                      # propose monitors for the jobs in a crontab
hellocron discover-server-apps          # detect services and create Server health monitors

discover-server-apps needs a management key (hellocron configure --management-key) and is described in the Server health preset guide.

Statuses

hellocron ping my-job run
hellocron ping my-job complete
hellocron ping my-job fail
hellocron ping my-job skip

Options

Flag	Description
`--tags <a,b>`	Comma-separated tags
`--project <name>`	Project the job belongs to
`--timeout <seconds>`	Expected maximum run time, sent with the `run` state
`[message]`	Free text after the state becomes the message (for example the error)

ping sends one state and nothing else. Duration, exit code and captured error output come from run, which wraps the command and sends both pings for you:

hellocron run db-backup --tags nightly pg_dump mydb > /tmp/backup.sql

Example with separate pings

hellocron ping db-backup run

pg_dump mydb > /tmp/backup.sql
EXIT=$?

if [ $EXIT -eq 0 ]; then
  hellocron ping db-backup complete
else
  hellocron ping db-backup fail "pg_dump exited with $EXIT"
fi
exit $EXIT

Checking your setup

Run doctor to verify that everything is configured correctly:

hellocron doctor          # checks config, API URL, key, connectivity
hellocron doctor --ping   # additionally sends a real test ping (state: skip)

It checks: HTTP tool availability (curl/wget), config file and its permissions, API URL and key, temp directory, API reachability (/health) and crontab access. Exit code is 0 when everything is OK, 1 when problems are found.

Using in Docker

Mount the script and config into your container:

volumes:
  - ./client/hellocron.sh:/usr/local/bin/hellocron:ro
  - ./client/.hellocron.conf:/root/.hellocron.conf:ro