> ## Documentation Index > Fetch the complete documentation index at: https://docs.expanse.sh/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > Every command the Expanse CLI exposes. The `expanse` CLI is the primary way to register compute, run workloads, and ask intelligence questions about them. ## Installation ```bash theme={"dark"} curl -fsSL https://expanse.sh/install | sh ``` *** ## Auth ### `expanse login` 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). ```bash theme={"dark"} # 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. ```bash theme={"dark"} 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`. ```bash theme={"dark"} 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. ```bash theme={"dark"} 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`. ```bash theme={"dark"} 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. ```bash theme={"dark"} 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. ```bash theme={"dark"} expanse metrics gpu-util gpu-memory-used --csv > gpu.csv expanse metrics cpu memory --interval 30s --agg max expanse metrics --job 41982 --source-type slurm gpu-util # resolve by SLURM job ID expanse metrics --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. ```bash theme={"dark"} 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: ```bash theme={"dark"} expanse analyse diff --artefact # inspect the patch expanse analyse apply --artefact # 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. ```bash theme={"dark"} expanse diagnose expanse diagnose 41982 --source-type slurm # scheduler-native job 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: ```bash theme={"dark"} expanse diagnose diff --artefact expanse diagnose apply --artefact # 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. ```bash theme={"dark"} 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` |