slurm-vscode 0.2.1
Launch Visual Studio Code directly on Slurm allocations via reusable holder jobs.
License: MIT
Requires Python: >=3.11

# slurm-vscode

`slurm-vscode` is a Typer-powered helper that keeps a Slurm allocation alive and opens Visual Studio Code directly against the compute node you receive.
Configuration, caching, and relaunch behaviour all live in one CLI so you can skip bespoke shell scripts.

> [!IMPORTANT]
> This prevents users from running VS Code directly on the login nodes, which keeps compute-heavy workloads on the correct resources.

## Features

- Reuse an existing holder job instead of waiting for a fresh allocation each time you launch VS Code.
- Configure defaults for login host, job name, poll interval, sbatch flags, `code` CLI path, and window reuse preference once via TOML.
- Cache the active JobID so you can quickly reconnect or cancel it later.
- Layer extra `sbatch` flags per launch without touching the config file.
- Inspect and tweak configuration keys with compact helper commands.

## Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Installation](#installation)
  - [Recommended: `uvx`](#recommended-uvx)
  - [Install once with `uv tool install`](#install-once-with-uv-tool-install)
  - [From a local checkout](#from-a-local-checkout)
- [Quick Start](#quick-start)
  - [SSH prerequisites](#ssh-prerequisites)
- [Command Overview](#command-overview)
- [Configuration Keys](#configuration-keys)
- [Development](#development)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Installation

### Recommended: `uvx`

Run the latest published build on demand without managing a virtual environment.

```bash
uvx slurm-vscode launch -- -p cpus -t 01:00:00 -N 1
```

`uvx` fetches and caches the package automatically, so this command always uses the newest release.

### Install once with `uv tool install`

Install the CLI on your `PATH` permanently and upgrade it with `uv tool upgrade` whenever you like.

```bash
uv tool install slurm-vscode
slurm-vscode launch -- -p cpus -t 00:30:00
```

### From a local checkout

The repository keeps a `uv` shebang for direct execution while developing or testing changes.

```bash
./slurm_vscode.py launch -- -p cpus -t 01:00:00 -N 1
```

## Quick Start

```bash
# 1. Create the default config and cache directories
slurm-vscode init

# 2. Launch VS Code on a GPU node (extra sbatch flags go after --)
slurm-vscode launch -- -p gpu -t 02:00:00 --gres=gpu:1
```

Prefer not to install anything? Swap `slurm-vscode` for `uvx slurm-vscode` in the commands above.

During `launch` the CLI performs the following steps.

1. Submits `sleep infinity` via `sbatch` using your configured defaults and any extra CLI flags.
2. Polls `squeue` until Slurm assigns a compute node.
3. Starts VS Code with `--reuse-window` (or `--new-window`) pointing at `ssh-remote+<node>`.
4. Stores the JobID so you can reuse the allocation or cancel it later with `slurm-vscode clear-cache` or `scancel <jobid>`.

If any step fails, newly submitted holder jobs are cancelled automatically unless you pass `--keep-job`.

### SSH prerequisites

`slurm-vscode` assumes you can reach your Slurm login host with passwordless SSH.
Configure your `~/.ssh/config` with an alias that matches the `login_host` value (the default is `mycluster`) and any proxy jumps required for compute nodes.
The example below assumes the compute nodes are named `mycluster-1`, `mycluster-2`, and so on:

```ssh-config
Host mycluster
    User myuser
    ForwardAgent yes

Host mycluster-*
    ProxyJump mycluster
    User myuser
    IdentityFile ~/.ssh/id_ed25519
    ForwardAgent yes
```

Replace `mycluster`, `myuser`, and the identity file path with values that match your environment.

## Command Overview

- `slurm-vscode init` writes a default `config.toml` in the standard platform config path if one does not exist.
- `slurm-vscode show|get|set` inspects or updates configuration keys.
- `slurm-vscode launch [-- options…]` reuses or submits a holder job, waits for a node, and opens VS Code while forwarding everything after `--` to `sbatch`.
- `slurm-vscode paths` reveals where config and cache files live.
- `slurm-vscode write-cache|read-cache|clear-cache` manages the cached JobID.

Run `slurm-vscode COMMAND --help` to see every option.

<details>
<summary><code>slurm-vscode --help</code> output</summary>

<!-- CODE:BASH:START -->
<!-- echo '```text' -->
<!-- export NO_COLOR=1 -->
<!-- export TERM=dumb -->
<!-- export TERMINAL_WIDTH=90 -->
<!-- ./slurm_vscode.py --help -->
<!-- echo '```' -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```text

 Usage: slurm_vscode.py [OPTIONS] COMMAND [ARGS]...

 Bootstrap configuration, cache a reusable Slurm allocation, and launch VS Code
 against it.

 Start a reusable VS Code session with: slurm-vscode launch -- -p cpus -t
 01:00:00 --gres=gpu:1 Add extra sbatch flags after --; everything before it
 configures the CLI. No install? Use uvx slurm-vscode launch -- … to run the
 latest release.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 1. Launch ──────────────────────────────────────────────────────────────────╮
│ launch         Submit (or reuse) a holder job, wait for a node, and launch   │
│                VS Code.                                                      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 2. Configuration ───────────────────────────────────────────────────────────╮
│ init           Create  config.toml  and supporting directories if they are   │
│                missing.                                                      │
│ show           Print the merged configuration TOML (defaults + overrides).   │
│ get            Print a single configuration value by key (or exit with 1 if  │
│                missing).                                                     │
│ set            Update a config key to a new value (bool, int, float, or      │
│                string).                                                      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 3. Job Memory ──────────────────────────────────────────────────────────────╮
│ remember-job   Remember a holder job so it can be reused later.              │
│ recall-job     Print the remembered JobID (if any) for quick reuse.          │
│ forget-job     Forget the remembered JobID.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 4. Introspection ───────────────────────────────────────────────────────────╮
│ paths          Print the resolved config and cache paths for convenience.    │
╰──────────────────────────────────────────────────────────────────────────────╯

```

<!-- OUTPUT:END -->

</details>

<details>
<summary><code>slurm-vscode launch --help</code> output</summary>

<!-- CODE:BASH:START -->
<!-- echo '```text' -->
<!-- export NO_COLOR=1 -->
<!-- export TERM=dumb -->
<!-- export TERMINAL_WIDTH=90 -->
<!-- ./slurm_vscode.py launch --help -->
<!-- echo '```' -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```text

 Usage: slurm_vscode.py launch [OPTIONS]

 Submit (or reuse) a holder job, wait for a node, and launch VS Code.

 Extra sbatch flags follow a  --  separator and are forwarded directly to
 sbatch . Example:  ./slurm_vscode.py launch -- -A proj -p gpu .

 When  --reuse-cache  (default) is enabled the command first tries to reuse a
 cached running job before submitting another. If node polling fails and
 --cancel-on-failure  is active the newly submitted job is cancelled
 automatically.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Overrides ──────────────────────────────────────────────────────────────────╮
│ --login-host        TEXT  Override config login host.                        │
│ --job-name          TEXT  Override the Slurm job name.                       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Polling ────────────────────────────────────────────────────────────────────╮
│ --poll-sec        FLOAT  How often to poll squeue for node assignment.       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ VS Code ────────────────────────────────────────────────────────────────────╮
│ --reuse-window    --new-window          Whether to reuse an existing VS Code │
│                                         window.                              │
│ --code-binary                     TEXT  Path to the VS Code command-line     │
│                                         binary.                              │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Cache Behaviour ────────────────────────────────────────────────────────────╮
│ --reuse-cache    --force-new      Reuse a cached holder job if available.    │
│                                   [default: reuse-cache]                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Job Lifecycle ──────────────────────────────────────────────────────────────╮
│ --cancel-on-failure    --keep-job      Cancel newly submitted jobs when      │
│                                        launch fails.                         │
│                                        [default: cancel-on-failure]          │
╰──────────────────────────────────────────────────────────────────────────────╯

```

<!-- OUTPUT:END -->

</details>

## Configuration Keys

| Key | Meaning |
| --- | ------- |
| `login_host` | SSH alias or bastion used to reach the Slurm login node. |
| `job_name` | Name assigned to the holder job. |
| `squeue_poll_sec` | Poll interval in seconds while waiting for node assignment. |
| `default_sbatch_flags` | Flags applied before any `launch` CLI extras. |
| `code_binary` | Command used to launch VS Code (`code` by default). |
| `code_reuse_window` | Whether `code` receives `--reuse-window` (`true`) or `--new-window`. |

Environment variables `LOGIN_HOST` and `SQUEUE_POLL_SEC` remain available for quick overrides, and every CLI option also accepts per-invocation values.

## Development

```bash
uv sync --all-extras
uv run pytest
```

Tests rely on monkeypatching subprocess calls, so they never touch your actual cluster or config directories.