📊 `pbs-tui`: TUI for PBS Job Scheduler Monitoring

Sam Foreman 2025-09-17

• 👀 Overview
• 🐣 Getting Started
• ✨ Features
  • 🎹 Key bindings
  • 🧪 Sample mode
  • Headless / automated runs
  • Inline snapshot mode
• Architecture
• Development notes
• Screenshots

Figure 1: A terminal dashboard for monitoring PBS Pro schedulers

👀 Overview

A terminal user interface built with Textual for monitoring PBS Pro schedulers at the Argonne Leadership Computing Facility.

The dashboard surfaces job, queue, and node activity in a single view and refreshes itself automatically so operators can track workload health in real time.

🐣 Getting Started

• Try it with uv:

  # install uv if necessary
  # curl -LsSf https://astral.sh/uv/install.sh | sh
  uv run --with pbs-tui pbs-tui

• Or install and run:

  python3 -m pip install pbs-tui
  pbs-tui

✨ Features

• Live PBS data – prefers the JSON (-F json) output of qstat/pbsnodes and falls back to XML or text parsing so schedulers without newer flags continue to work.

  • Automatic refresh – updates every 30 seconds by default with a manual refresh binding (r).
  • Summary cards – quick totals for job states, node states, and queue health.

• Inline snapshot – render the current queue as a Rich table with pbs-tui --inline

  • Save to file – write the snapshot to a Markdown file with pbs-tui --inline --file snapshot.md

• Fallback sample data – optional bundled data makes it easy to demo the interface without connecting to a production scheduler (PBS_TUI_SAMPLE_DATA=1).

🎹 Key bindings

🧪 Sample mode

If you want to explore the UI without a live PBS cluster, export PBS_TUI_SAMPLE_DATA=1 (or pass force_sample=True to PBSDataFetcher). The application will display bundled example jobs, nodes, and queues along with a warning banner indicating that the data is synthetic.

Headless / automated runs

For automated testing or CI environments without an interactive terminal you can run the TUI in headless mode by exporting PBS_TUI_HEADLESS=1. Pairing this with PBS_TUI_AUTOPILOT=quit presses the q binding automatically after startup so pbs-tui exits cleanly once the interface has rendered its first update.

Inline snapshot mode

When running non-interactively you can emit a Rich-rendered table summarising the active PBS jobs instead of starting the Textual interface:

PBS_TUI_SAMPLE_DATA=1 pbs-tui --inline

The command prints a table that can be pasted into terminals that support Unicode box drawing. Pass --file snapshot.md alongside --inline to also write an aligned Markdown table to snapshot.md for sharing in chat or documentation systems. Any warnings raised while collecting data are written to standard error so they remain visible in logs.

Architecture

• pbs_tui.fetcher.PBSDataFetcher orchestrates qstat/pbsnodes calls, preferring JSON output and falling back to XML/text before converting everything into structured dataclasses (Job, Node, Queue).
• pbs_tui.app.PBSTUI is the Textual application that renders the dashboard, periodically asks the fetcher for new data, and updates the widgets.
• pbs_tui.samples.sample_snapshot provides the demonstration snapshot used when PBS commands cannot be executed.

The UI styles are defined in pbs_tui/app.tcss. Adjust the CSS to change layout or theme attributes.

Development notes

• The application refresh interval defaults to 30 seconds. Pass a different value to PBSTUI(refresh_interval=...) if desired.
• Errors encountered while running PBS commands are surfaced in the status bar so operators can quickly see when data is stale.
• When both PBS utilities are unavailable and the fallback is disabled, the UI will show an empty dashboard with an error message in the status bar.

Screenshots

• pbs-tui:

  

• Keys and Help Panel:

  

• Command palette:

  

• theme support: