Name: srest
Author: SergioZ3R0

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 and extract the binary for your platform from GitHub Releases - no Go installation required.

                    # Linux amd64

                    curl -LO https://github.com/SergioZ3R0/srest/releases/latest/download/srest-linux-amd64.zip

                    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, srest-windows-amd64.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 or an encrypted vault file.

Priority: Environment variables > Encrypted vault (~/.srest/config.vault) > Defaults.

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.
`SLURM_INSECURE`	No	Set to `true` to skip TLS certificate verification.
`SLURM_CA_CERT`	No	Path to a PEM-encoded CA certificate for custom/self-signed TLS endpoints.
`SREST_VAULT_PASS`	No	Password to auto-decrypt the vault (skips interactive prompt).

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

Encrypted Vault

srest can store your JWT and connection settings in an AES-256-GCM encrypted file at ~/.srest/config.vault. The vault is protected by a password you choose at creation time.

Create a vault

srest vault init
# Prompts for: vault password, Slurm URL, JWT token, username

Run with vault

# Interactive password prompt
./srest

# Or skip the prompt with an environment variable
SREST_VAULT_PASS=myscret ./srest

Vault commands

Command	Description
`srest vault init`	Create a new encrypted vault with interactive prompts.
`srest vault encrypt`	Encrypt an existing plain `~/.srest/config` file into a vault.
`srest vault decrypt`	Decrypt and display the vault contents (for inspection).
`srest vault edit`	Decrypt, edit in `$EDITOR`, and re-encrypt.

How it works

Encryption: AES-256-GCM with a PBKDF2-derived key (100,000 iterations, SHA-256).
File format: SREST_VAULT_V1 magic header + 16-byte salt + 12-byte IV + ciphertext.
Vault path: ~/.srest/config.vault (permissions 0600).
Priority: Environment variables always override vault values.

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
`↑/↓` / `j/k`	Navigate table rows
`PgUp/PgDn` / `b/f`	Page up / page down
`Ctrl+U/Ctrl+D`	Half page up / down
`Home/End` / `g/G`	Go to start / end
`enter`	Select / drill-down
`/`	Filter the current table
`ctrl+r`	Refresh (Jobs, Nodes, Partitions)
`x`	Cancel selected job (Jobs tab)
`r`	Requeue selected job (Jobs tab) / Run request (Query tab)
`ctrl+o`	About modal
`?`	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 ctrl+r to refresh. Press x to cancel or r to requeue the selected job.

Nodes tab

Cluster nodes with state, CPUs, GPU usage, memory and partitions. Select a node to see its detail (including GPU load bars). Press / to filter.

Partitions tab

Partition list with configured/total nodes, CPU and GPU load bars, and max wall time. Select a partition to see its detail. Press / to filter. Press enter to view jobs in that partition.

Query tab

Visual query builder with 33 endpoints organized in three categories:

slurm - ping, jobs, job detail, nodes, node detail, partitions, reservations, shares.
slurmdb - associations, accounts, clusters, users, qos, tres, wckeys, jobs, diag, config.
actions - submit job, job action (cancel/requeue/hold/release), node state (drain/resume), create association.

Navigate categories with tab/[], endpoints with ↑/↓. Path parameters (like {job_id}) are shown in yellow. Press e in the Response panel to export the response to JSON.

Query tab keys

Key	Action
`f` / `F`	Cycle panels forward / backward (Sidebar/Builder/Response/History/Raw)
`tab` / `[]`	Switch category (slurm / slurmdb / actions)
`↑/↓`	Navigate endpoints (sidebar) or parameters (builder)
`←/→`	Cycle parameter options
`enter`	Edit parameter / start custom query input
`esc`	Exit custom query edit mode
`r`	Run the built request
`e`	Export response to JSON (Response panel) / Open $EDITOR for script param
`del` / `x`	Clear the selected parameter's value

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

Encrypted vault - store JWT and connection settings in an AES-256-GCM encrypted file (~/.srest/config.vault); credentials never sit plain on disk.
TLS support - custom CA certificates (SLURM_CA_CERT) or skip verification (SLURM_INSECURE).
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). Cancel (x) and requeue (r) jobs directly from the TUI.
Nodes - cluster nodes with state, CPUs, GPU usage, memory and partitions; select a node for details.
Partitions - partition list with configured/total nodes, CPU and GPU load bars, max wall time.
Query builder - 33 endpoints across slurm/slurmdb/actions with sidebar navigation, path parameters, and cluster-gathered options.
Custom query - type or paste any request path to run it directly.
Response export - export any query response to a pretty-printed JSON file.
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.
About modal - press ctrl+o for ASCII banner, version info, and links.

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.

srest Documentation

Contents