kuma-stats

A read-only terminal dashboard for Uptime Kuma: current monitor state, uptime percentages, response time, and heartbeat history.

kuma-stats is an independent project and is not affiliated with or endorsed by Uptime Kuma.

Install

Requires Python 3.10 or later.

pip install kuma-stats
# or install as an isolated command-line tool
uv tool install kuma-stats
# pipx install kuma-stats

Verify the installation:

kuma-stats --version

Quick start

Set the Uptime Kuma URL and a server-issued JWT token. Environment variables are preferred for automation; do not pass passwords or tokens as command-line arguments because they can be exposed in shell history or process listings.

export KUMA_URL=https://kuma.example.com
export KUMA_TOKEN=your-server-issued-jwt
kuma-stats list
kuma-stats --format json uptime

Alternatively, create a .env file in the directory where you run the command:

KUMA_URL=https://kuma.example.com
KUMA_TOKEN=your-server-issued-jwt

kuma-stats loads this working-directory .env without overwriting environment variables. Keep it out of version control.

To create a token with username/password credentials already supplied through environment variables, use:

export KUMA_USERNAME=your-username
export KUMA_PASSWORD=your-password
kuma-stats login --store-keyring

The keyring is the preferred token store. login --store-token writes an owner-only .env file; use it only when the OS keyring is unavailable.

Commands

Examples:

kuma-stats list
kuma-stats status 1 2
kuma-stats beats 1 --hours 48
kuma-stats --format yaml uptime
kuma-stats --format json list

Table output is the default. Use --format json or --format yaml for structured output. JSON and YAML errors are written to stderr with a stable code and message.

Configuration

Values are resolved in this order, from highest to lowest precedence:

1. Command-line options
2. Environment variables
3. A .env file in the working directory
4. User configuration: $XDG_CONFIG_HOME/kuma-stats/config.toml on Linux
5. An OS-keyring token

Use KUMA_CONFIG_FILE to select a different TOML file. Example:

url = "https://kuma.example.com"
format = "table" # table, json, or yaml
timeout = 30
max_retries = 2
insecure = false

TLS certificate verification is enabled by default. Use --insecure only for a trusted self-signed server. Invalid or unreadable TOML configuration files fail with an INVALID_CONFIGURATION error instead of being ignored.

Compatibility

kuma-stats supports Python 3.10–3.12 and uses the maintained uptime-kuma-api client for Uptime Kuma communication. CI smoke-tests token authentication, password login, failed authentication, and list telemetry against a disposable Uptime Kuma 1.23.16 Docker container. It uses no external server or credentials.

Development

make setup
make verify
make live-test # requires Docker

make verify runs linting, type checks, tests, builds wheel/sdist artifacts, and validates their metadata. make live-test runs the separately gated Docker compatibility smoke test; it creates disposable credentials and state and never contacts a production server.

Releasing

Releases are intentionally manual. Draft notes from the commits since the last release:

make release-prep

Use the printed prompt with an LLM if useful, review its suggested Keep a Changelog entry, then update CHANGELOG.md and src/kuma_stats/__init__.py. Preview and create the GitHub Release:

make release-dry
make release

make release requires a clean main worktree, a new versioned changelog section, and confirmation. It validates the project, creates and pushes an annotated vX.Y.Z tag, then attaches the validated wheel and sdist to a GitHub Release. PyPI publishing is a separate deliberate step:

uv run twine upload dist/*

See docs/RELEASING.md for PyPI/TestPyPI account setup, local token storage, testing, and troubleshooting.

Security and support

See SECURITY.md for private vulnerability reporting, CONTRIBUTING.md for the maintenance policy, and CHANGELOG.md for release history.

License

Distributed under the MIT License.