# Slurm Task Manager - stama
[](https://github.com/Gordi42/stama/actions/workflows/ci.yml)
A terminal user interface for monitoring and managing slurm jobs.
# Content:
- [Installation](#installation)
- [Shell completions](#shell-completions)
- [Usage](#usage)
# Installation
## Prebuilt binaries
Download a prebuilt binary from the [GitHub releases page](https://github.com/Gordi42/stama/releases). 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
```bash
curl https://sh.rustup.rs -sSf | sh
```
2. Install stama using the cargo package manager
```bash
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:
```bash
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
# 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:
```toml
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](notes.md)
# Author
Silvano Rosenau