CLI Reference - Expanse

The expanse CLI is the primary way to register compute, run workloads, and ask intelligence questions about them.

Installation

curl -fsSL https://expanse.sh/install | sh

Auth

Store your personal exp_user_* API key locally and mint a session. Pass the key with --api-key or set EXPANSE_API_KEY (the key is created from the Console settings page after you sign in through your organisation’s SSO).

# provide your exp_user_* key with --api-key (or set EXPANSE_API_KEY):
expanse login --api-key exp_user_…

Flag	What it does
`--api-key`	User API key (defaults to `EXPANSE_API_KEY`)
`--control-plane`	Control-plane URL, for self-hosted deployments (defaults to `EXPANSE_API_URL` or your existing session)
`--organisation-id`	Organisation to mint the session for

`expanse status`

Show which identity the CLI is acting under.

expanse status

`expanse refresh`

Mint and cache a fresh short-lived access token for the current session. The CLI does this automatically; use refresh to force one, or to switch organisation with --organisation-id.

expanse refresh

Compute

`expanse compute register`

Register a new compute with your organisation. The command asks what kind of compute you’re registering (or pass --type) and prints a single-use install token plus the install command to run on the target.

expanse compute register

Flag	What it does
`--type`	Compute type (`slurm`, `kubernetes`, `nomad`)
`--name`	Compute name (default: derived from the type and timestamp)
`--team-id`	Team to bind the compute to (team IDs are on the Console Teams page)

`expanse compute install`

Run on the target machine. Exchanges the install token (set EXPANSE_INSTALL_TOKEN) for the compute’s stable credential and writes the daemon config. expanse compute register prints the exact command to run, including --control-plane and --data-plane.

EXPANSE_INSTALL_TOKEN=… expanse compute install \
  --control-plane https://… --data-plane https://… \
  --type slurm --daemon-version v1.2.1

With --type slurm the installer downloads the daemon release named by --daemon-version, verifies its checksum and cosign signature against the pinned Expanse release signing key, places the daemon and scheduler hooks, and enables the systemd unit. --daemon-binary installs a pre-staged binary or release archive instead (the air-gapped path; archives are verified against the same key). --write-config-only skips cluster orchestration and only writes the config file. --reinstall (alias --force) re-runs the install on a node that already holds a daemon config. With EXPANSE_INSTALL_TOKEN unset it reuses the existing credential and needs no token. With EXPANSE_INSTALL_TOKEN set to a token re-issued from the compute’s console page, it exchanges that token and replaces the credential for the same compute. Reinstall never prompts for a token.

Workloads

`expanse executions`

List recent workload executions for your organisation, newest first. The quickest way to find an execution ID for expanse diagnose or expanse metrics without opening the Console.

expanse executions                          # 25 most recent
expanse executions --status failed          # only failed runs
expanse executions --outcome out_of_memory  # only OOM-killed runs
expanse executions --mine                   # runs you submitted

The table shows the execution ID, scheduler-native job ID, submitting user, status, outcome, start time, and a Console link.

Flag	What it does
`--limit`	Maximum executions returned (default 25)
`--status`	Filter by status (`queued`, `running`, `succeeded`, `failed`, `cancelled`, `unknown`)
`--outcome`	Filter by outcome (`success`, `failure`, `cancelled`, `timeout`, `out_of_memory`, `unknown`)
`--user`	Filter by submitting user
`--mine`	Filter to executions you submitted
`--compute`	Target compute ID
`--json`	Print the raw JSON response

The submitting user comes from the scheduler and is best-effort: executions whose telemetry carried no user stay unattributed and are not matched by --user or --mine.

`expanse metrics`

Export metric series for one execution as a summary table, CSV, or JSON.

expanse metrics <execution-id> gpu-util gpu-memory-used --csv > gpu.csv
expanse metrics <execution-id> cpu memory --interval 30s --agg max
expanse metrics --job 41982 --source-type slurm gpu-util   # resolve by SLURM job ID
expanse metrics <execution-id> --dcgm --all --csv          # every DCGM counter

Name at least one metric: gpu-util, gpu-memory-used, gpu-memory-total, gpu-power, gpu-temp, gpu-clock, cpu, memory. Any other name is passed through raw, so CUPTI PM sampling and DCGM counters keep their native names.

Flag	What it does
`--csv`	Long-format CSV to stdout, one row per point: `timestamp,metric,source,gpu_index,gpu_uuid,value,min,max,avg,sample_count,unit`
`--json`	Raw JSON responses to stdout
`--interval`	Aggregation bucket width in whole seconds, for example `5s` or `1m`
`--agg`	Bucket aggregation: `avg` (default), `min`, `max`, `sum`, `p95`, `last`
`--since`	Window relative to now, for example `2h`
`--from` / `--to`	Window start and end (RFC 3339); intersected with the execution’s own lifecycle window
`--gpu`	Restrict to one GPU index
`--allow-fallback`	Widen to compute scope when the execution has no scoped data (may include other jobs’ GPUs)
`--cupti` / `--dcgm`	Only CUPTI PM sampling / only DCGM series
`--all`	Discover and export every metric for the selected source (requires `--cupti` or `--dcgm`)
`--job` / `--source-type`	Resolve the execution by scheduler-native job ID (`slurm`, `kubernetes`, `nomad`)
`--max-points`	Maximum points per series (default 5000)

--csv and --json write data to stdout only; progress and warnings go to stderr, so piped output stays machine-clean. When a series hits --max-points the CLI warns on stderr and suggests a wider --interval.

Intelligence

`expanse analyse`

Recommend resources before a workload runs. Accepts a SLURM batch script, a source file, a Kubernetes workload manifest, or a Nomad jobspec.

expanse analyse train.slurm                 # SLURM batch script
expanse analyse train.py                    # source file
expanse analyse job.yaml                    # Kubernetes workload manifest
expanse analyse job.nomad                   # Nomad jobspec

The output is RESOURCE RECOMMENDATION (walltime, CPU, host memory, GPU count and type, the measured GPU peak and utilisation of earlier runs, and completion_probability, the probability a run completes at the recommended resources computed from every recorded run of the same source), FAILURE RISK at the resources you requested, OPTIMISATION (the resource change proposed, as a class such as memory_lower+walltime_raise), followed by the executions on your compute that anchored the numbers. Units live in the row name (_s, _gb, _pct); the one confidence label is low, medium or high, with the fit score beside it when recorded runs anchor the result. Analyse proposes resource changes only, never code changes, unless you pass --code. When the recommendation changes your submission, analyse produces a patch artefact and, on an interactive terminal, asks Apply the resource recommendations automatically? [y/n]: y shows the diff and applies it, n leaves these commands for later:

expanse analyse diff <run-id> --artefact <artefact-id>    # inspect the patch
expanse analyse apply <run-id> --artefact <artefact-id>   # apply it locally

Flag	What it does
`--compute`	Target compute ID
`--cpu` / `--memory` / `--gpu` / `--walltime`	Requested resources, for example `--memory 16GiB --walltime 2h`
`--json`	Print the raw JSON response
`--no-cache`	Force a fresh analysis instead of returning the cached run
`--no-patch`	Skip patch artefacts; return the recommendation numbers only (`OPTIMISATION` reads `none`)
`--yes`	Apply the resource patch without asking (never code patches; not with `--json`, `--no-patch` or `--queue`)
`--code`	Also propose a code patch when a device-memory gap cannot be fixed by resources, for example a recorded CUDA out-of-memory run of the same source; the interactive prompt applies it after you review the diff (not with `--no-patch` or `--yes`)
`--queue`	Queue analyse runs instead of waiting for recommendations

analyze works as a spelling alias.

`expanse diagnose`

Root cause of a failed execution, with cited evidence and a prompt for your coding agent. The output opens with PIPELINE DIAGNOSE (what evidence each stage found), then the execution’s identity, RESOURCE SNAPSHOT (same names and units as expanse analyse, GPU memory per device) and, for a failed run, FAILURE DETECTION: the failure pattern, the confidence label, recurrence (the share of this workload’s earlier recorded runs that failed) and the root cause.

expanse diagnose <execution-id>
expanse diagnose 41982 --source-type slurm    # scheduler-native job ID

<execution-id> is the Expanse execution ID (find it with expanse executions). If you only have the scheduler-native ID, pass it with --source-type (slurm, kubernetes, nomad). The diagnosis cites the evidence it used: telemetry, logs, the captured source bundle, and similar executions on your compute. Diagnose never proposes or applies a fix. A failed execution carries a prompt for your own coding agent, which owns the change. On an interactive terminal diagnose offers it (Suggested prompt for your agent? [y/n]); --prompt prints it bare for piping into a clipboard tool:

expanse diagnose <execution-id> --prompt | pbcopy    # xclip or wl-copy on Linux

Flag	What it does
`--source-type`	Treat the argument as a scheduler-native job ID from this source
`--source`	Source file to include as evidence (repeatable)
`--compute`	Target compute ID
`--prompt`	Print only the prompt for your coding agent, for piping to a clipboard tool
`--json`	Print the raw JSON response
`--no-cache`	Force a fresh diagnosis instead of returning the cached run

Other

`expanse version`

Print the CLI version.

expanse version

Environment variables

Variable	What it does
`EXPANSE_API_KEY`	Personal `exp_user_*` key, read by `expanse login`
`EXPANSE_API_URL`	Override the control-plane URL (defaults to your organisation’s deployment)
`EXPANSE_INSTALL_TOKEN`	Single-use install token consumed by `expanse compute install`
`EXPANSE_CONSOLE_URL`	Console base URL for the links printed by `expanse executions`

​Installation

​Auth

​expanse login

​expanse status

​expanse refresh

​Compute

​expanse compute register

​expanse compute install

​Workloads

​expanse executions

​expanse metrics

​Intelligence

​expanse analyse

​expanse diagnose

​Other

​expanse version

​Environment variables