slurmhub 1.1.0

A terminal UI for monitoring Slurm jobs in real-time over SSH

---

A keyboard-driven terminal UI for monitoring Slurm jobs in real time over SSH. It runs the standard Slurm command-line tools (squeue, sacct, scontrol, sinfo, sstat, nvidia-smi, scancel) against one or more clusters, parses the output, and presents the result as a rich dashboard built with Textual.

Features

• Real-time job table — active jobs from squeue merged with recent history from sacct, color-coded by state.
• Per-job detail screen — scontrol stats with time / memory / per-GPU utilisation bars; one keystroke to the stdout, stderr, or submitted batch script.
• Cluster dashboard — cluster-wide CPU / GPU / memory bars, partition summary, per-node table fed by sinfo.
• Multi-cluster tabs — configure several clusters and switch with h / l; filter, search, and sort state is remembered per tab.
• Persistent job history & analytics (H) — a local SQLite database records every run, its resource usage over time, and your favourites; browse, filter, and see GPU / CPU / memory-hour aggregates. On by default; --demo ships a seeded history.
• Favourites & notes — star important runs (f) and annotate them (n); starred runs are exempt from history retention.
• Vim-style navigation throughout.
• OSC 52 yank — copy job IDs, paths, and log lines to the system clipboard through SSH, no xclip / pbcopy required.
• First-run wizard that writes a working TOML config and tests the SSH connection.
• Demo mode (--demo) — exercise the entire TUI against built-in fixture data, no cluster needed.

Installation

slurmhub is published on PyPI and requires Python ≥ 3.12 and an OpenSSH client.

The recommended installers are uv or pipx — both install slurmhub into its own isolated environment so its dependencies don't pollute your system Python:

# uv (https://docs.astral.sh/uv/)
uvx slurmhub                         # one-shot run
uv tool install slurmhub             # persistent install on $PATH

# pipx (https://pipx.pypa.io/)
pipx install slurmhub

# plain pip — works, but consider a venv first
pip install --user slurmhub

Then:

slurmhub --demo    # try it without an SSH connection
slurmhub           # run against your configured cluster(s)

Or clone and run from source (for development):

git clone https://github.com/matteospanio/slurmhub.git
cd slurmhub
uv sync
uv run slurmhub

Quick start

1. Run slurmhub. If no config exists at ~/.config/slurmhub/config.toml, the first-run wizard walks you through creating one.

2. Set up passwordless SSH to your cluster — ssh-copy-id your key and add a Host alias in ~/.ssh/config.

3. Reference the alias in your config:

   [profiles.mycluster]
   host = "mycluster"
   

Full SSH and configuration walkthrough: docs site → Getting started.

Documentation

The full documentation lives at matteospanio.github.io/slurmhub.

• Getting started — installation, quickstart, SSH setup
• Configuration — TOML schema, profiles, log paths, worked examples
• Usage guides — job table, detail screen, log viewer, cluster dashboard, batch script, scancel
• Reference — keybindings, info sources, troubleshooting
• Changelog — release notes

Sphinx sources are under docs/. Build locally with:

uv sync --group docs
uv run sphinx-build -b html docs docs/_build/html

Development

uv sync --group dev
uv run pytest                       # run the test suite (417 tests)
pre-commit install                  # enable code-quality hooks
uv run python docs/scripts/generate_screenshots.py  # regenerate docs SVGs

See CLAUDE.md for project context and development notes.

License

GPL-3.0 © Matteo Spanio