Skip to main content

Create a Slurm Queue Snapshot CLI

Level: Beginner · Time: 30–40 min · Category: Command line

Tags: Python · Slurm · Prompting

Use AI coding assistance to create a beginner Python CLI that summarizes Slurm queue output.

This tutorial assumes you can open a terminal on a system where Slurm commands such as squeue are available. You will ask the assistant for the first implementation, then refine it.

Prerequisites​

Requires an active HPC account on Sol

This tutorial runs real Slurm commands such as squeue and cannot be completed without an HPC account on the Sol supercomputer. HPC accounts require a faculty sponsor — only sponsored users (or faculty themselves) can be approved. Request one through Getting Access and Requesting an Account before you start.

  • LLM API Guide — set up AI coding assistance before asking for edits or explanations.
  • OpenCode setup — use OpenCode to explain Slurm output and iterate on the script.
  • RC docs — review cluster usage and login-node expectations.

Confirm Python 3 is available and that you can reach the Slurm client on a login node:

python3 --version    # expect 3.9 or newer
squeue --version     # confirms the Slurm client is installed

If python3 is missing, load a Python module (for example module load python). If squeue is not found, connect to a Slurm login node before continuing.

What you will do​

  • Set up a Python CLI workspace.
  • Ask for a script that calls squeue safely.
  • Add terminal-friendly output and JSON output.
  • Practice asking for a small feature and a parser test.

Build it step by step​

1. Create the CLI workspace​

Install a small terminal formatting dependency and a test runner. The assistant can use these without making the script complicated.

mkdir slurm-queue-snapshot
cd slurm-queue-snapshot
python3 -m venv .venv
source .venv/bin/activate
pip install rich pytest
Keep this out of Git

If you track this project with Git, do not commit your virtual environment or any secrets. Create a .gitignore file in the project folder with at least these lines:

.gitignore
.venv/
.env
__pycache__/

.venv/ is large and specific to your machine, and .env holds your API key — neither belongs in a shared repository. New to Git? See Track a New Project with Git.

2. Capture sample Slurm output​

Before prompting, collect a small example. Real command output makes the assistant much better at writing a parser.

  • Run this on a Slurm login node.
  • Remove or anonymize usernames if needed before pasting output into an AI tool.
  • Keep the sample short: three to ten rows is enough.
squeue -h -o '%.18i|%.18u|%.12T|%.10M|%.10l|%.18P|%.30j' | head > sample-squeue.txt

3. Ask for the first CLI​

A good CLI prompt names the commands to call, the desired flags, and how errors should behave.

You are helping me build a beginner Python command-line tool for Slurm.

Project goal:
- Run squeue from Python.
- Parse the output into structured rows.
- Print a readable queue summary table.
- Add a --json flag so the output can later feed a dashboard.

Constraints:
- Use argparse and subprocess.
- Use the rich package for readable terminal output.
- Keep the first version in one file named queue_snapshot.py.
- Handle the case where squeue is not available and print a helpful error.

Please:
1. Create the first version of queue_snapshot.py.
2. Explain how the parsing works.
3. Show the commands to run it.

4. Ask for one feature and a test​

Once the first version runs, ask for a narrow improvement. This is where AI assistance is most useful for beginners.

Please add one feature to the Slurm CLI:

Feature:
- Add a --user option that filters jobs to one username.

Constraints:
- Keep --json working.
- Keep the default behavior unchanged when --user is not provided.
- Add a small parser test using saved sample squeue output.
- Explain how to run the test.
python queue_snapshot.py --limit 5
python queue_snapshot.py --json
pytest

More prompts to try​

  • Explain this Slurm CLI line by line for someone new to Python subprocess.
  • Add a --state filter for RUNNING or PENDING jobs. Keep --json and --user working.
  • Review this parser for assumptions that might break on another cluster.

Troubleshooting​

  • If squeue is not found, you are probably not on a Slurm login node or Slurm is not in PATH.
  • If parsing fails, paste a few anonymized lines of actual squeue output and ask the assistant to adjust the parser.
  • If the assistant tries to run jobs or modify Slurm state, stop and restate that this tool is read-only.
  • If terminal output looks messy, ask for a plain table first, then add rich formatting after the data is correct.

Next steps​