CLI Usage

The crond-agent CLI wraps any command and reports its exit code, duration, and (by default) captured stdout/stderr to crond.io. It handles SIGTERM gracefully so wrapped jobs get a clean shutdown under Kubernetes pod termination or systemd preemption.

Already need to install? See Installation — script, brew, deb, rpm, docker, manual, k8s helm.

Basic usage

Wrap any command with the exec subcommand, followed by your monitor's ping key UUID and -- before the wrapped command:

crond-agent exec --key YOUR-PING-KEY -- /usr/local/bin/backup.sh

The agent sends a start ping before launching, then a success ping on exit code 0 or a fail ping on any non-zero exit. Both terminal pings include the duration, exit code, and captured output.

Env vars instead of flags

Set CROND_PING_KEY (and optionally CROND_API_URL for self-hosted) to keep cron lines tidy:

export CROND_PING_KEY=abc-123-def-456
crond-agent exec -- /usr/local/bin/backup.sh

Timeouts

Cap a wrapped command's wall-clock time with --timeout. The agent sends SIGTERM at the deadline, waits a 10-second grace period, then SIGKILL:

crond-agent exec --key YOUR-PING-KEY --timeout 30m -- /opt/long-backup.sh

Crontab example

Replace a plain cron command with the agent wrapper:

# Before
0 2 * * * /usr/local/bin/backup.sh

# After
0 2 * * * crond-agent exec --key YOUR-PING-KEY -- /usr/local/bin/backup.sh

A working cron.d example covering the common patterns ships with the .deb / .rpm at /usr/share/doc/crond-agent/cron.d.example.

Privacy: redaction + capture opt-out

By default the wrapped command's stdout/stderr is included in the ping payload. Two settings let you scrub or drop it. They live in /etc/crond-agent/config.yaml (system install) or as env vars on the cron line:

# /etc/crond-agent/config.yaml
capture_output: true              # default — set false to drop captured streams entirely
redact_patterns:                  # Go regexps; matches -> "[REDACTED]"
  - 'Bearer [A-Za-z0-9._-]+'
  - 'postgres://[^@]+@[^/[:space:]]+'
  - '(?i)(password|api[_-]?key|secret)\s*[:=]\s*\S+'

Equivalent env vars: CROND_CAPTURE_OUTPUT=false and CROND_REDACT_PATTERNS as a newline-separated list (newline avoids conflicts with commas inside regex quantifiers like .{1,40}). Patterns are validated as regexes at startup and the agent aborts if any are malformed.

Redaction is line-buffered and runs before the truncation cap, so a secret straddling the cap boundary is still caught. The host stdout/stderr passthrough (kubectl logs, /var/log/cron) is not redacted — that stream is the operator's local view.

See Security for the full threat model.

Subcommands

Subcommand	Description
exec [flags] -- <cmd>	Wrap and monitor a command (most common)
ping [flags]	Send a single success ping; useful for liveness checks
config	Print the effective merged config as YAML (ping key is redacted)
install [--target]	Self-copy the binary to <target>. Used by the K8s init-container pattern.
version	Print version, commit, build date

exec flags

Flag	Description
--key	Ping key UUID (or set CROND_PING_KEY env var)
--api-url	API base URL (or CROND_API_URL); default https://api.crond.io
--timeout 30m	Wall-clock cap; SIGTERM at deadline, SIGKILL 10s later
--passthrough-stdout=false	Disable tee of child stdout/stderr to the host stream (default on)

Exit codes

The agent's own exit code mirrors the wrapped command's exit code (0-255). Signal-terminated children exit 128 + signal following shell convention — SIGTERM → 143, SIGKILL → 137 — so && chained cron pipelines behave the same with and without the wrapper.