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

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.