Slurm Task Manager - stama

A terminal user interface for monitoring and managing slurm jobs.

Content:

• Installation
• Shell completions
• Usage

Installation

Prebuilt binaries

Download a prebuilt binary from the GitHub releases page. For clusters, the x86_64-unknown-linux-musl build is recommended: it is a static binary that works on old login nodes without root or a Rust toolchain.

Install with cargo

1. Prerequisites: Rust compiler rustc and the rust packager manager cargo. They can be installed with

curl https://sh.rustup.rs -sSf | sh

2. Install stama using the cargo package manager

cargo install --locked stama

The --locked flag makes cargo use the exact dependency versions that stama was tested with. The program 'stama' should now be available in your terminal.

Shell wrapper function

(Optional): To enable some functions, for example 'cd to working directory of selected job', add the following function to the config file of your shell, e.g. '($HOME)/.bashrc' for bash, or '($HOME)/.zshrc' for zsh:

stama_wrapper() {
  temp_file="$(mktemp -t "stama.XXXXXXXXXX")"
  stama --output-file="$temp_file"
  output=$(cat -- "$temp_file")
  # Check if the output is "cd /some/path/"
  if [[ "$output" == "cd "* ]]; then
    local directory="${output#cd }"  # Extract the directory path
    cd "$directory"
  # Check if the output is "ssh <some_address>"
  elif [[ "$output" == "ssh "* ]]; then
    local node="${output#ssh }"  # Use the output as the SSH command
    ssh -Y "$node"
  # An empty output means stama was quit normally, so stay silent
  elif [[ -n "$output" ]]; then
    echo "Unknown command in stama output: $output"
  fi
  rm -f -- "$temp_file"
}

After restarting your terminal or sourcing the config file, you can use the function 'stama_wrapper' to execute the commands output by stama.

Shell completions

Stama can generate completion scripts for bash, zsh and fish with the --completions flag:

# bash
stama --completions bash > ~/.local/share/bash-completion/completions/stama

# zsh (make sure the directory is in your $fpath)
stama --completions zsh > ~/.zfunc/_stama

# fish
stama --completions fish > ~/.config/fish/completions/stama.fish

Usage

1. Starting stama: Stama can be started by executing 'stama' or 'stama_wrapper' in your terminal.
2. All keybindings: The keybindings info can be accessed by pressing '?' inside stama.
3. User settings: The user settings menu can be accessed by pressing 'o' inside stama. The available options can be modified by selecting them and pressing 'enter'.
4. Job actions: The job actions menu of the selected job can be accessed by pressing 'enter' inside stama. Available job actions are:
   • Cancel job (only with permission)
   • Open job output file in editor (default: vim, can be changed in user settings)
   • Open job submission script in editor (default: vim, can be changed in user settings)
   • cd to working directory of selected job (only in stama_wrapper)
   • ssh to node of selected job (only in stama_wrapper)
5. Job allocation: The job allocation menu can be accessed by pressing 'a' inside stama. The job allocation menu shows a list of saved salloc commands New presets can be created by navigating to the 'create new' entry.
6. Change squeue command: Press '/' or click on the squeue command with the mouse to change the squeue command, 'squeue' without any additional arguments will show all running jobs from all users.
7. Filter the job list: Press 'f' to filter the visible jobs while typing (case-insensitive substring over the displayed columns; input containing regex characters is matched as a regular expression when it compiles, e.g. gpu|cpu). 'Enter' keeps the filter active (the job list then shows filter: <text> (matching/total)), 'Esc' clears it. The filter only narrows the display — sorting, notifications and the squeue command still see all jobs.

Configuration

Stama stores its settings in '($HOME)/.config/stama/config.toml'. All settings can be changed from within stama in the user settings menu ('o'), including the columns of the job table ("Job columns", a comma-separated list). Alternatively, edit the config file directly. For example, to show the job priority instead of the node count:

job_columns = ["id", "name", "status", "time", "partition", "priority"]

Available columns: id, name, status, time, partition, nodes, priority, reason, account, qos, cpus, nodelist. Clicking a column header (or pressing 'tab') sorts the job list by that column. If job_columns is missing from the config file, the default columns id, name, status, time, partition, nodes are used.

Stama can also notify you when a job starts (pending → running) or finishes (running → completed/failed/timeout/cancelled): notify_bell = true rings the terminal bell (once per refresh, even if several jobs change at once), and notify_desktop = true sends a desktop notification via the OSC 777 escape sequence (supported by kitty, foot, WezTerm and Ghostty; harmlessly ignored by other terminals). Both options are off by default.

Tasks of the same job array (e.g. 12345_1, 12345_2, ..., or the pending placeholder 12345_[8-99]) are collapsed into a single expandable row 12345[] that shows aggregate status counts (e.g. 3R 10PD 37CD). Press Space (or click the selected group row) to expand or collapse the tasks. "Kill job" on a group row cancels the whole array (scancel <base id>); the other actions apply to the group's first task. Set group_job_arrays = false to disable the grouping (on by default).

For more infos see: notes.md

Author

Silvano Rosenau