srest Documentation | Slurm REST API TUI

Requirements

Go 1.24+ to build from source.
A running slurmrestd endpoint with JWT authentication (for authenticated operations).
Network access to the slurmrestd HTTP API.

Installation

Pre-built binaries (recommended)

Download the zip for your platform from GitHub Releases and extract it — no Go installation required.

unzip srest-linux-amd64.zip
chmod +x srest

Platforms: srest-linux-amd64.zip, srest-linux-arm64.zip, srest-darwin-amd64.zip, srest-darwin-arm64.zip.

From source

git clone https://github.com/SergioZ3R0/srest.git
cd srest
go build -o srest .

Or use the Makefile:

make build
# install to ~/.local/bin (or override with PREFIX)
make install

Note: Run make help to see all available targets.

Configuration

srest is configured through environment variables:

Variable	Required	Description
`SLURM_URL`	No	Base URL of slurmrestd (default `http://localhost:6820`).
`SLURM_JWT`	Yes*	JWT token for the `X-SLURM-USER-TOKEN` header.
`SLURM_USER_NAME`	No	User for `X-SLURM-USER-NAME` (defaults to the current OS user).
`SLURM_API_VERSION`	No	API version (e.g. `v0.0.45`). If omitted, it is auto-detected.

Note: * Required for endpoints that need authentication; can be omitted on a JWT-less slurmrestd.

export SLURM_URL=http://localhost:6820
export SLURM_JWT=$(scontrol token | cut -d= -f2)
export SLURM_USER_NAME=slurm
./srest

Usage & key bindings

srest opens a tabbed TUI. Navigate tabs and interact with the data.

Key	Action
`q` / `Ctrl+C`	Quit
`tab` / `]`	Next tab
`shift+tab` / `[`	Previous tab
`esc`	Go to Dashboard
`/`	Filter the current table
`r`	Refresh (Jobs tab)
`?`	Toggle help

Dashboard

Real-time overview: nodes up/down, jobs running/pending/completed/failed, partitions and accounts.

Jobs tab

Your jobs (filtered by the authenticated user). Select a job to see its detail: account, partition, time limit, run time, assigned nodes, log paths and exit code (when finished). Press / to filter by any column. Press r to refresh.

Nodes tab

Cluster nodes with state, CPUs, memory and partitions. Select a node to see its detail. Press / to filter.

Partitions tab

Partition list with configured/total nodes and max wall time. Select a partition to see its detail. Press / to filter. Press j to view jobs in that partition.

Query tab

A Postman-style request composer with three user-focused endpoints:

ping — connectivity check against slurmrestd.
get jobs — query jobs with filters: state, account, partition, qos, node, users. Account, partition and qos options are gathered live from the cluster.
submit jobs — submit a job with name, partition, qos, account, gres, wall time, nodes, cpus/task, memory, script. Partition, account, qos and gres options are gathered from the cluster. Press e to open $EDITOR.

Query builder keys

Key	Action
`1-3`	Select endpoint (ping / get jobs / submit jobs)
`↑/↓`	Navigate parameters
`←/→`	Cycle the selected parameter's options (state, partition, qos, account, gres)
`enter`	Edit the selected parameter's value
`e`	Open `$EDITOR` for the script parameter
`del` / `backspace` / `x`	Clear the selected parameter's value
`f`	Cycle focus between builder / response / custom query / history
`r`	Run the built request (GET or POST submit)

Custom query

Switch to the Custom query panel with f, then type or paste a full request path (e.g. /jobs?state=RUNNING or /slurmdb/v0.0.45/jobs?users=alice) and press enter to run it.

Features

Dashboard — real cluster overview: nodes up/down, jobs by state, partitions and accounts.
Jobs — your jobs (filtered by the authenticated user), with a detail panel (account, partition, time limit, run time, assigned nodes, log paths, exit code).
Nodes — cluster nodes with state, CPUs and memory; select a node for details.
Partitions — partition list with configured/total nodes, max wall time; press j to filter jobs.
Query builder — build requests against ping, get jobs and submit jobs with parameters gathered live from the cluster (state, account, partition, qos, gres).
Custom query — type or paste any request path to run it directly.
Request history — every request is logged with status, duration and warnings. Persisted across sessions in ~/.local/share/srest/history.json (max 100 entries).
Version auto-detection — adapts to the slurmrestd data_parser (v0.0.40–45) and version-gates fields.

Test Lab

To try srest against a real Slurm cluster (slurmctld, slurmdbd and slurmrestd) without setting up infrastructure, see the test lab guide:

docs/test-lab.md — spin up a Slurm test cluster with Docker.