hc-cli

A command-line client for Healthchecks.io, built with uv, ty, and pytest.

Supports the full v3 management API (checks CRUD, pause/resume, ping/flip history, channels, badges, status) plus outgoing pings to hc-ping.com with start/success/fail/exit-code/log variants. Works against the SaaS instance or self-hosted Healthchecks.

Install

uv sync                       # install runtime + dev deps from uv.lock
uv run hc --help              # smoke test the CLI

To install globally as a tool:

uv tool install .
hc --help

Configure

Resolution order: --flag > env var > config file > built-in default.

Setting	Env var	Default
API key	HEALTHCHECKS_API_KEY	(required for mgmt API)
API URL	HEALTHCHECKS_API_URL	https://healthchecks.io
Ping URL	HEALTHCHECKS_PING_URL	https://hc-ping.com

Config file at $XDG_CONFIG_HOME/hc-cli/config.toml (defaults to ~/.config/hc-cli/config.toml), overridable with --config PATH:

api_key  = "your-project-api-key"
api_url  = "https://healthchecks.io"
ping_url = "https://hc-ping.com"

Usage

--json can be placed at the root or on a subcommand:

hc checks list                       # all checks, table view
hc checks list --tag prod --json     # filter by tag, JSON output
hc --json checks list --tag prod     # equivalent, root-level flag
hc checks get <uuid>
hc checks create --name "nightly etl" --schedule "0 2 * * *" --tz UTC
hc checks update <uuid> --grace 600
hc checks pause <uuid>
hc checks resume <uuid>
hc checks delete <uuid> --yes

hc pings list <uuid>
hc pings body <uuid> --n 42
hc flips list <uuid> --seconds 86400

hc channels list
hc badges list
hc status

# Outgoing pings (no API key required)
hc ping <uuid>                       # success
hc ping <uuid> --start
hc ping <uuid> --fail
hc ping <uuid> --exitcode 0
hc ping <uuid> --log --body-file ./run.log
hc ping <uuid> --rid "$(uuidgen)" --start

Develop

uv sync
uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run pytest