Getting Started

Getting started

Language: English · فارسی

Install

The package on PyPI is called pulsecheckcli; the command it installs is pulsecheck, and pck is a shorter alias for the same command.

uv tool install pulsecheckcli     # or: pipx install pulsecheckcli
pulsecheck init                   # config + .env + shoutrrr + cron job
pulsecheck env                    # put your tokens in the .env file
pulsecheck validate && pulsecheck test-notify

See Commands for what each command does and YAML reference for every config key.

One line (Linux)

curl -fsSL https://raw.githubusercontent.com/arian24b/pulsecheck/main/install.sh | bash

It installs uv if missing, runs uv tool install --upgrade pulsecheckcli (if PyPI cannot be reached it installs from the GitHub repository instead), then runs pulsecheck init. If a terminal is available, init asks before it downloads shoutrrr and adds the cron job; without one it runs with --yes. Extra arguments go to init: ... | bash -s -- --no-cron. To install something else set PULSECHECK_SOURCE, for example PULSECHECK_SOURCE=git+https://github.com/arian24b/pulsecheck@main. Run it again to upgrade (or use pulsecheck update).

Manual install

Requirements

• uv (it installs the right Python for you; Python 3.12–3.15 is supported, 3.15 preferred)
• Docker, or the shoutrrr binary on PATH (see Notifications)
• ping only if you use type: ping (Linux iputils-ping)

Get the code

git clone https://github.com/arian24b/pulsecheck && cd pulsecheck
# (for a GitHub Actions setup with the fewest files use the template: https://github.com/arian24b/pulsecheck-template)
uv sync
cp pulsecheck.example.yml pulsecheck.yml

Check the config and the alerts

export TG_TOKEN=... TG_CHAT=@mychannel API_TOKEN=...   # whatever ${VARS} your file uses
uv run pulsecheck validate        # parses the file, fails on mistakes
uv run pulsecheck test-notify     # sends a test message to the global notify urls

Run

uv run pulsecheck run             # check every site that is due
uv run pulsecheck run --force     # ignore per-site intervals
uv run pulsecheck run --fail-on-down   # exit code 1 if any site is down (shows red in CI)
uv run pulsecheck status          # current state of every site (--json, --md)
uv run pulsecheck run --tag prod  # only sites tagged prod (also for status and report)
uv run pulsecheck report          # uptime % and response times
uv run pulsecheck report --json
uv run pulsecheck -c other.yml run     # use another config file (put -c before the command)

Output is one line per site, for example web: up 131ms.

Next: schedule it.