Metadata-Version: 2.4
Name: pulsecheckcli
Version: 0.2.1
Summary: Self-hosted uptime monitor: HTTP/TCP/ping/TLS checks, shoutrrr alerts, OpenTelemetry export. Runs from cron, CI or serverless.
Keywords: uptime,monitoring,shoutrrr,alerts,opentelemetry,cron,healthcheck
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: System :: Monitoring
Requires-Dist: cfuicli>=1.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: ruamel-yaml>=0.19.1
Requires-Python: >=3.12, <3.16
Project-URL: Homepage, https://github.com/arian24b/pulsecheck
Project-URL: Documentation, https://github.com/arian24b/pulsecheck/wiki
Project-URL: Issues, https://github.com/arian24b/pulsecheck/issues
Project-URL: Changelog, https://github.com/arian24b/pulsecheck/releases
Description-Content-Type: text/markdown

# pulsecheck

**English** · [فارسی](README.fa.md)

Self-hosted uptime monitor. It checks HTTP(S) endpoints, TCP ports and hosts (ping) on a schedule, tracks up / down / slow state, and sends alerts through [shoutrrr](https://github.com/nicholas-fedor/shoutrrr) (Slack, Telegram, Discord, email, ntfy and 20+ more). One YAML file, one state file, no dashboard, no git history.

## Features
- HTTP checks: method, headers, body, expected status, redirect limit, max response time, "slow" (degraded) threshold
- TLS certificate expiry warnings (`ssl_warn_days`) and expired-certificate failures
- TCP and ping checks, each optionally forced over IPv4 or IPv6 (`ip_version`)
- Alerts only on change, `down_after` to ignore blips, optional repeat reminders (`remind_every`)
- Per-site tags, intervals and alert routing; UTC maintenance windows
- Editable alert texts by key (`messages:`)
- `status` (text, JSON, markdown) and `report` (uptime %, response times) without a dashboard
- OpenTelemetry push (OTLP/HTTP JSON metrics and logs) to any collector or webhook
- Setup commands: `init` (config, `.env`, shoutrrr, cron; no questions, flags decide), `env`, `validate`, `test-notify` to every channel, `update`
- `${ENV}` substitution, so secrets stay out of the config
- Runs from GitHub Actions, GitLab CI, cron, or serverless on Vercel and Cloudflare Workers (see the [limits](https://github.com/arian24b/pulsecheck/wiki/Serverless))
- Python 3.12–3.15 (3.15 preferred), managed with [uv](https://docs.astral.sh/uv/)

## Install
```bash
uv tool install pulsecheckcli     # or: pipx install pulsecheckcli
pulsecheck init                   # config + .env + shoutrrr + cron job (Linux)
pulsecheck env                    # add your tokens
pulsecheck validate && pulsecheck test-notify
```
The package is `pulsecheckcli`; the command is `pulsecheck`, and `pck` is a short alias for it. All commands: [Commands](https://github.com/arian24b/pulsecheck/wiki/Commands).

### Or: one line from GitHub (Linux)
```bash
curl -fsSL https://raw.githubusercontent.com/arian24b/pulsecheck/main/install.sh | bash
```
It installs the PyPI package `pulsecheckcli` with `uv tool` and runs `pulsecheck init`. Then run `pulsecheck env`, `pulsecheck validate` and `pulsecheck test-notify`.

## How it works

Each `pulsecheck run` loads the YAML, picks the sites whose `interval` has elapsed (`--force` checks all) and checks them concurrently (HTTP, TCP or ping). The result goes into a SQLite file (`state_file`, default `pulsecheck.db`). A site becomes `down` after `down_after` consecutive failures, and `degraded` when it answers slower than `slow_ms`. An alert is sent only when the state changes (plus optional reminders), by running `shoutrrr send` through its docker image or a local binary. Nothing stays running: schedule `run` with cron, GitHub Actions or GitLab CI.

Example run against a local web server and a closed port (`down_after: 1`):

```console
$ pulsecheck -c pulsecheck.yml run --fail-on-down; echo $?
local: up 30ms
closed: down 0ms ConnectionRefusedError: [Errno 111] Connection refused
1
$ pulsecheck -c pulsecheck.yml status
🟢 local                up        for 0s    last 0s     24h 100.0%
🔴 closed               down      for 0s    last 0s     24h 0.0%
```

## Quick start (from a clone)
```bash
uv sync
cp pulsecheck.example.yml pulsecheck.yml     # edit it
uv run pulsecheck validate
uv run pulsecheck test-notify
uv run pulsecheck run [--force] [--fail-on-down] [--tag prod]
uv run pulsecheck status [--json|--md]
uv run pulsecheck report [--json]
```
shoutrrr runs from its docker image when Docker works, otherwise from the `shoutrrr` binary on `PATH`. `ping` is needed for `type: ping`.

Want it running on GitHub Actions with the fewest files? Click **Use this template** on [pulsecheck-template](https://github.com/arian24b/pulsecheck-template): you get just `pulsecheck.yml`, one workflow and a short README. **Keep your copy private**: `pulsecheck.yml` lists your hostnames.

## Documentation (wiki)
| | English | فارسی |
|---|---|---|
| Overview | [Home](https://github.com/arian24b/pulsecheck/wiki/Home) | [خانه](https://github.com/arian24b/pulsecheck/wiki/FA-Home) |
| Every command | [Commands](https://github.com/arian24b/pulsecheck/wiki/Commands) | [دستورها](https://github.com/arian24b/pulsecheck/wiki/FA-Commands) |
| Install and first run | [Getting started](https://github.com/arian24b/pulsecheck/wiki/Getting-Started) | [شروع سریع](https://github.com/arian24b/pulsecheck/wiki/FA-Getting-Started) |
| Every YAML key (types, defaults) | [YAML reference](https://github.com/arian24b/pulsecheck/wiki/YAML-Reference) | [مرجع YAML](https://github.com/arian24b/pulsecheck/wiki/FA-YAML-Reference) |
| Every setting, explained | [Configuration](https://github.com/arian24b/pulsecheck/wiki/Configuration) | [تنظیمات](https://github.com/arian24b/pulsecheck/wiki/FA-Configuration) |
| Alert services | [Notifications](https://github.com/arian24b/pulsecheck/wiki/Notifications) | [اعلان‌ها](https://github.com/arian24b/pulsecheck/wiki/FA-Notifications) |
| GitHub / GitLab / cron | [Scheduling](https://github.com/arian24b/pulsecheck/wiki/Scheduling) | [زمان‌بندی](https://github.com/arian24b/pulsecheck/wiki/FA-Scheduling) |
| Vercel / Cloudflare | [Serverless](https://github.com/arian24b/pulsecheck/wiki/Serverless) | [سرورلس](https://github.com/arian24b/pulsecheck/wiki/FA-Serverless) |
| How it works, what is tested | [Design notes](https://github.com/arian24b/pulsecheck/wiki/Design-Notes) | [یادداشت‌های طراحی](https://github.com/arian24b/pulsecheck/wiki/FA-Design-Notes) |
| Problems | [Troubleshooting](https://github.com/arian24b/pulsecheck/wiki/Troubleshooting) | [عیب‌یابی](https://github.com/arian24b/pulsecheck/wiki/FA-Troubleshooting) |

Questions: [Discussions](https://github.com/arian24b/pulsecheck/discussions). Contributing: [CONTRIBUTING](https://github.com/arian24b/pulsecheck/blob/main/.github/CONTRIBUTING.md). Security: [SECURITY](https://github.com/arian24b/pulsecheck/blob/main/.github/SECURITY.md).

## Troubleshooting and security

- No alerts arrive: run `pulsecheck test-notify`. It sends to every channel and shows the shoutrrr error, if any. Also check `notify.events` and that the site has been failing for `down_after` runs.
- `type: ping` fails: the `ping` command must be installed.
- `pulsecheck.yml` lists your hostnames, and `.env` holds tokens. Keep both out of public repositories and reference secrets as `${VAR}`.
- More: [Troubleshooting](https://github.com/arian24b/pulsecheck/wiki/Troubleshooting).

## Development
```bash
uv run pytest -q && uv run ruff check . && uv run ruff format --check .
```
Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, ...): the version, `CHANGELOG.md`, the GitHub release and the PyPI upload are generated from them by python-semantic-release.

## License
MIT

## Common commands

Built on [cfuicli](https://github.com/arian24b/cfui), so it looks and behaves like the other tools in this family.

```bash
pulsecheck help [command]     # help; -h works on any command
pulsecheck version            # version and git repository (also: -v)
pulsecheck update [--check]   # update the tool itself; --check only compares versions
pulsecheck -q ...             # quiet: no banner or notes (or PULSECHECK_QUIET=1)
```

- A missing required option is asked for when you run the tool in a terminal. In a pipe or in CI it stops with `--flag is required. Pass --flag <value> or run interactively.` (exit code 2).
- Errors appear in a red box on stderr with a non-zero exit code. Ctrl-C exits with 130.
- Color is used only on a terminal. `NO_COLOR=1` turns it off.
- `pulsecheck init` takes `--no-cron`, `--no-download`, `--force` and `--cron EXPR`; `--remove-cron` removes the cron job it added. The global `-c/--config FILE` can go before or after the command.
