Stoei

A terminal UI for monitoring Slurm jobs. It auto-refreshes every 5 seconds and summarizes jobs, nodes, and users.

Install & Launch

Jobs

Nodes

Users

Priority

Filtering

Features

• Auto-refreshing job list (5s)
• Job stats (running, pending, requeues)
• Job history (last 24 hours)
• Job detail view (Enter or i)
• Tabs for Jobs, Nodes, Users, and Priority
• Quick filtering (/)

Installation

Run with uvx (no install)

Prerequisite: install uv.

uvx git+https://github.com/pjhartout/stoei.git

Specific version:

uvx git+https://github.com/pjhartout/stoei.git@v0.2.7

Optional alias:

alias stoei='uvx git+https://github.com/pjhartout/stoei.git'

Install as a tool (uv)

uv tool install git+https://github.com/pjhartout/stoei.git

Upgrade or uninstall:

uv tool install --upgrade git+https://github.com/pjhartout/stoei.git
uv tool uninstall stoei

From source

git clone https://github.com/pjhartout/stoei.git
cd stoei
uv sync
uv run stoei

Editable install (development)

Install from a local checkout so source changes take effect immediately:

git clone https://github.com/pjhartout/stoei.git
cd stoei
uv pip install -e .

Or to make stoei available on your PATH in editable mode:

uv tool install -e .

Alternative: pip

pip install git+https://github.com/pjhartout/stoei.git

Usage

stoei

If you are using uvx directly:

uvx git+https://github.com/pjhartout/stoei.git

Keyboard shortcuts

Key	Action
q	Quit
r	Refresh
i	Enter job ID
Enter	View selected job details
↑/↓	Navigate jobs
Tab	Switch tables
1	Jobs tab
2	Nodes tab
3	Users tab

Requirements

• Python 3.11+
• Slurm commands available: squeue, sacct, scontrol

Development

git clone https://github.com/pjhartout/stoei.git
cd stoei
uv sync --all-extras
uv run pre-commit install

Run tests:

uv run pytest

Lint and format:

uv run ruff format --check .
uv run ruff check .

Type check:

uv run ty check stoei/

Mock Slurm data:

./scripts/run_with_mocks.sh

If you run the TUI during development, use timeout 10 stoei to avoid hanging.

Logging

Logs are written to stdout and ~/.stoei/logs/. Files rotate daily and are kept for 1 week.

Releases

Tags on GitHub create releases. See the releases page.

License

MIT License - see LICENSE for details.

Contributing

Before opening a PR, run tests, lint, format, and type checks as described in CONTRIBUTING.md.

Related projects

GitHub is full of related projects. Fundamentally I just wanted a way to easily look at my logs, cancel and monitor requeued jobs, which I don't think is supported by existing solutions.

What's in a name?

stoei is a Dutch verb meaning "wrestle", because that's what it feels like sometimes to manage these jobs... it's also an alternative spelling for SLURM Terminal User Interface (STUI).