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

With --type slurm the installer also places the daemon and scheduler hooks and enables the systemd unit; --write-config-only skips cluster orchestration and only writes the config file.

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 a resource recommendation (CPU, memory, GPU, walltime) with a confidence label, predicted failure risks, optimisation suggestions, and the executions on your compute that anchored the numbers. When the recommendation changes your submission, analyse produces a patch artefact and prints the commands to review and apply it:

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
`--queue`	Queue analyse runs instead of waiting for recommendations

analyze works as a spelling alias.

`expanse diagnose`

Solution-oriented guidance for a failed execution.

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. When the evidence supports a concrete fix, diagnose produces a patch artefact. On an interactive terminal it offers to show and apply the patch; otherwise inspect and apply it explicitly:

expanse diagnose diff <run-id> --artefact <artefact-id>
expanse diagnose apply <run-id> --artefact <artefact-id>   # add --yes to skip confirmation

Flag	What it does
`--source-type`	Treat the argument as a scheduler-native job ID from this source
`--source`	Source file to include for fix generation (repeatable)
`--compute`	Target compute ID
`--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