Metadata-Version: 2.4
Name: cmtop
Version: 0.2.0
Summary: realtime htop-style monitor for chatmail relays
Project-URL: Repository, https://github.com/hpk42/cmtop
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil
Requires-Dist: rich
Requires-Dist: xdg-base-dirs
Requires-Dist: textual
Dynamic: license-file

# cmtop: real-time mail monitor for chatmail relays


`cmtop` provides an `htop`-style console interface for
monitoring mail traffic and system health on chatmail relays.
It tails postfix and dovecot logs to calculate real-time delivery
statistics and identifies external domains involved in mail traffic.


## Installation


To install use:

    uv tool install cmtop


## Usage


### Interactive TUI


To run the interactive TUI:

    cmtop


To override the local domain name used for distinguishing
internal versus external traffic:

    cmtop --domain example.org


### Non-interactive Log Analysis


To analyze a logfile and print a flat summary table:

    cmtop -f /path/to/mail.log


You can also pipe `journalctl` output directly:

    journalctl -u postfix@- --no-pager | cmtop -f - --domain mail.example.org


## Interactive Controls


- `j` or Down Arrow: Move cursor down

- `k` or Up Arrow: Move cursor up

- `q`: Quit


## Developing / Releasing cmtop


1. Clone the git repository at https://github.com/hpk42/cmtop

2. Install 'cmtop' in editing mode: `uv pip install -e .`

3. Edit code under `cmtop/`, add tests to `tests/` and run `pytest`,
   finally commit your changes.

CI checks (ruff lint/format, packaging, pytest) come from the shared
[chatmail/workflows](https://github.com/chatmail/workflows)
repository; run them locally with `uvx ruff check .`,
`uvx ruff format --check .` and `pytest`.

To release, run the shared release script from a checkout of
[chatmail/workflows](https://github.com/chatmail/workflows):

    python ../workflows/scripts/make_new_release.py

It runs the checks, tests the built wheel, generates the CHANGELOG.md
entry with git-cliff and opens it in your editor, then commits, tags
vX.Y.Z and pushes. The release.yml workflow builds and publishes to
PyPI via trusted publishing (OIDC); no local twine or PyPI token is
involved.
