PBS Pro Textual TUI

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.

Racks Grid (Polaris)	Cluster Grid (Polaris)
Racks Grid (Aurora)	Cluster Grid (Aurora)

More views & themes

Cluster Grid (dark)	Jobs Table (dark)
Cluster Grid (light)	Jobs Table (light)
Cluster Grid (Catppuccin)	Cluster Grid (One Dark)

• Try it out!

  # if you still haven't installed uv:
  # curl -LsSf https://astral.sh/uv/install.sh | sh
  uvx pbs-tui
  

Features

• Cluster grid – visual map of cluster node utilization with proportional legend bar. Click a job block to see its details. Colors adapt to the active theme.
• Rack grid – per-rack node-level view modeled on the ALCF status page. Click a node to highlight every node a job occupies; click a rack name to filter the job sidebar. Detects Aurora and Polaris cabinet hostnames; falls back to a generic layout for other clusters.
• 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).
• Rich tables – sortable (via cursor) tables for jobs, nodes, and queues with detail views for the selected record.
• Themes – ships with pbs-dark, pbs-light, ansi-dark, and ansi-light themes. The ansi-* variants use muted 256-color palette tones that blend with your terminal colorscheme. Switch via the command palette (Ctrl+P).
• Fallback sample data – bundled realistic mock cluster (~560 nodes, ~40 jobs) for demoing without a production scheduler (pbs-tui --dummy, or PBS_TUI_SAMPLE_DATA=1).
• Inline snapshot – render the current queue as a Rich table with pbs-tui --inline and optionally write a Markdown summary alongside it.

Installation

uv pip install pbs-tui

Usage

Launch the dashboard once the PBS CLI utilities (qstat, pbsnodes) are on the PATH:

pbs-tui

The same entry point is available via python -m pbs_tui. The interface displays a summary panel, tables for jobs/nodes/queues, and a detail pane for the selected row. Refreshing happens automatically; press r to force an immediate update.

Adjust the refresh cadence with pbs-tui --refresh-interval 60 (seconds) if you prefer a slower or faster polling loop.

Key bindings

Use tab and the arrow keys/PageUp/PageDown to move through rows once a table has focus.

Sample mode

If you want to explore the UI without a live PBS cluster, run pbs-tui --dummy (aliases: --fake, --sample), 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.