Commands

Commands

Language: English · فارسی

pulsecheck [-c FILE] <command>      # `pck` is a shorter alias: pck status, pck run, ...

Without -c, pulsecheck uses ./pulsecheck.yml, then ~/.config/pulsecheck/pulsecheck.yml. A .env file next to the config file is loaded automatically (variables already set in the environment win; empty KEY= lines count as not set).

Command	What it does
pulsecheck help [command]	Help for everything or for one command (-h works too)
pulsecheck init	First-time setup on Linux (below)
pulsecheck env	Opens the .env file in your editor
pulsecheck validate	Checks the config file and your alert URLs
pulsecheck test-notify	Sends a test message to every alert channel
pulsecheck run	Checks the sites that are due (--force, --tag, --fail-on-down)
pulsecheck status	Current state of every site (--json, --md, --tag)
pulsecheck report	Uptime % and response times (--json, --tag)
pulsecheck update	Upgrades pulsecheck (--check only compares versions)
pulsecheck --version	Prints the version

init

Creates what a new user needs, then asks before the two system changes:

1. ~/.config/pulsecheck/pulsecheck.yml from the built-in example (state file under ~/.local/state/pulsecheck/). An existing config is never overwritten unless you pass --force.
2. ~/.config/pulsecheck/.env (mode 600) with an empty line for every ${VAR} the config uses.
3. shoutrrr: if Docker works it offers to pull the image; otherwise it offers to download the checksum-verified binary to ~/.local/bin.
4. A cron job (*/5 * * * * by default) in your user crontab, inside a marked block, using flock so runs never overlap. Output goes to ~/.local/state/pulsecheck/run.log.

Options: -y/--yes (no questions), --no-cron, --no-download, --cron "*/10 * * * *", --force, and --remove-cron (only removes the block that init added). Running init again replaces the block instead of adding a second one. It needs Linux and the crontab program (package cron).

env

Opens ~/.config/pulsecheck/.env in $VISUAL, $EDITOR, or nano/vim/vi, creating it if needed. When you close the editor it lists the variables the config uses that are still empty. pulsecheck env --path prints the path only. The cron job reads this file too, so you do not need to put secrets in the crontab.

validate

Parses the config (unknown keys and bad values are errors), prints a summary, warns if there are no alert URLs, and asks shoutrrr to verify each alert URL (--no-verify skips that). Secrets are never printed: channels are shown as telegram://***.

test-notify

Sends the test message to the global alert URLs and to every site-level notify URL (each once), and to the OpenTelemetry endpoint if one is configured. Prints sent or FAILED with the reason per channel; the exit code is 1 if any failed.

update

Finds out how pulsecheck was installed and runs the right upgrade: uv tool upgrade pulsecheckcli, pipx upgrade pulsecheckcli, git pull for a git clone, or pip install --upgrade pulsecheckcli. It prints the command before running it.

Install from PyPI

uv tool install pulsecheckcli (or pipx install pulsecheckcli), then pulsecheck init. The PyPI project is pulsecheckcli; the command stays pulsecheck. Releases are published from GitHub with a PyPI Trusted Publisher (no token is stored).