Metadata-Version: 2.4
Name: kuma-stats
Version: 0.3.0
Summary: Read-only CLI for Uptime Kuma monitor status, uptime, and heartbeat data
Project-URL: Homepage, https://github.com/crcatala/kuma-stats
Project-URL: Repository, https://github.com/crcatala/kuma-stats
Project-URL: Issues, https://github.com/crcatala/kuma-stats/issues
Project-URL: Security, https://github.com/crcatala/kuma-stats/security/policy
Author-email: Christian Catalan <crcatala@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,monitoring,status,uptime,uptime-kuma
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: keyring>=24.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: uptime-kuma-api>=1.2.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# kuma-stats

[![CI](https://github.com/crcatala/kuma-stats/actions/workflows/ci.yml/badge.svg)](https://github.com/crcatala/kuma-stats/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/kuma-stats)](https://pypi.org/project/kuma-stats/)
[![Python](https://img.shields.io/pypi/pyversions/kuma-stats)](https://pypi.org/project/kuma-stats/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A read-only terminal dashboard for [Uptime Kuma](https://github.com/louislam/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.

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

Verify the installation:

```bash
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.

```bash
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:

```dotenv
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:

```bash
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

| Command | Description |
| --- | --- |
| `login [--store-token \| --store-keyring]` | Authenticate and print or securely save a server-issued JWT |
| `list` | List all monitors and current telemetry |
| `status [ID…]` | Show details and recent heartbeats; omit IDs for all monitors |
| `beats ID [--hours N]` | Show heartbeat history for one monitor |
| `uptime` | Show 24-hour, 30-day, and one-year uptime |

Examples:

```bash
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:

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

| Variable | Purpose |
| --- | --- |
| `KUMA_URL` | Uptime Kuma server URL |
| `KUMA_TOKEN` | Server-issued JWT token |
| `KUMA_USERNAME`, `KUMA_PASSWORD` | Login credentials; required for `login` without a token |
| `KUMA_FORMAT` | Default output format: `table`, `json`, or `yaml` |
| `KUMA_TIMEOUT` | Per-connection timeout and overall retry budget in seconds |
| `KUMA_MAX_RETRIES` | Retry count for transient connection failures |
| `KUMA_INSECURE` | Set to `true` only for a trusted self-signed server |
| `NO_COLOR` | Disable terminal colour |

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`](https://github.com/lucasheld/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](https://hub.docker.com/layers/louislam/uptime-kuma/1.23.16/images/sha256-431fee3be822b04861cf0e35daf4beef6b7cb37391c5f26c3ad6e12ce280fe18) Docker container. It uses no external server or credentials.

## Development

```bash
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:

```bash
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:

```bash
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:

```bash
uv run twine upload dist/*
```

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

## Security and support

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

## License

Distributed under the [MIT License](LICENSE).
