> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Loops CLI reference

> Deploy and inspect Loops sessions, runs, samplers, and checkpoints using the Truss CLI.

The `truss loops` command provides subcommands for the [Loops](/loops/concepts) deployment lifecycle: pushing a run for a base model, viewing runs and samplers, reporting GPU usage, and listing or deploying checkpoints from a run.

```sh theme={"system"}
truss loops [OPTIONS] COMMAND [ARGS]...
```

| Command                                     | Description                                             |
| ------------------------------------------- | ------------------------------------------------------- |
| [`push`](#push)                             | Provision a session, run, and sampler for a base model. |
| [`deactivate`](#deactivate)                 | Deactivate a Loops run and its paired sampler.          |
| [`view`](#view)                             | List Loops runs.                                        |
| [`logs`](#logs)                             | Fetch logs for a Loops run or its paired sampler.       |
| [`usage`](#usage)                           | Report Loops GPU capacity across deployments.           |
| [`runs view`](#runs-view)                   | Deprecated: use [`view`](#view).                        |
| [`samplers view`](#samplers-view)           | Deprecated: use [`usage`](#usage).                      |
| [`checkpoints view`](#checkpoints-view)     | List checkpoints for a Loops run.                       |
| [`checkpoints deploy`](#checkpoints-deploy) | Deploy checkpoints from a Loops run.                    |

***

## `push`

Provision a Loops session, run, and paired sampler for a base model. If the project already has an active Loops deployment for the base model, the command fails with a validation error.

```sh theme={"system"}
truss loops push [OPTIONS] BASE_MODEL
```

### Arguments

<ParamField body="BASE_MODEL" type="TEXT" required>
  Hugging Face model ID for the base model (for example, `Qwen/Qwen3-8B`).
</ParamField>

### Options

<ParamField body="--project-id" type="TEXT">
  Training project ID to associate the deployment with.
</ParamField>

<ParamField body="--replicas" type="INTEGER">
  Number of data-parallel trainer replicas to provision. The trainer deployment runs this many copies of the base model's preset node group (for example, `--replicas 4` on a 4-node preset provisions 16 nodes across 4 data-parallel workers). Must be a positive integer; defaults to 1.
</ParamField>

<ParamField body="--remote" type="TEXT">
  Name of the remote in `.trussrc` to deploy to.
</ParamField>

<ParamField body="--log" type="humanfriendly | W | WARNING | I | INFO | D | DEBUG" default="humanfriendly">
  Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.
</ParamField>

<ParamField body="--non-interactive">
  Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.
</ParamField>

**Example:**

```sh theme={"system"}
truss loops push Qwen/Qwen3-8B
```

***

## `deactivate`

Deactivate a Loops run, tearing down both of its halves: the trainer and its paired sampler. Saved checkpoints remain accessible after deactivation. Identify the run with `--run-id`, using the run ID from `truss loops view`.

```sh theme={"system"}
truss loops deactivate [OPTIONS] [DEPLOYMENT_ID]
```

### Arguments

<ParamField body="DEPLOYMENT_ID" type="TEXT" deprecated>
  Passing a Loops deployment ID as a positional argument is deprecated; use `--run-id` instead.
</ParamField>

### Options

<ParamField body="--run-id" type="TEXT">
  Loops run ID to deactivate.
</ParamField>

<ParamField body="--remote" type="TEXT">
  Name of the remote in `.trussrc`.
</ParamField>

<ParamField body="-y, --yes">
  Skip the confirmation prompt.
</ParamField>

<ParamField body="--log" type="humanfriendly | W | WARNING | I | INFO | D | DEBUG" default="humanfriendly">
  Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.
</ParamField>

<ParamField body="--non-interactive">
  Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.
</ParamField>

**Example:**

```sh theme={"system"}
truss loops deactivate --run-id <run_id> --yes
```

***

## `view`

List Loops runs. Each row is a single run, keyed by its run ID, with a run-level status. Lists your own runs by default; pass `--org` to list every run in your organization, which adds an Owner column to the output. The command hides inactive runs unless you pass `--all`.

```sh theme={"system"}
truss loops view [OPTIONS]
```

### Options

<ParamField body="--remote" type="TEXT">
  Name of the remote in `.trussrc`.
</ParamField>

<ParamField body="--all">
  Include inactive runs.
</ParamField>

<ParamField body="--org">
  List every Loops run in your organization (with its owner), not just your own.
</ParamField>

<ParamField body="-r, --reverse">
  Reverse the default order (oldest first) so the most recent run is shown first.
</ParamField>

<ParamField body="-o, --output-format" type="cli-table | json" default="cli-table">
  Output format: cli-table (default) or json.
</ParamField>

<ParamField body="--log" type="humanfriendly | W | WARNING | I | INFO | D | DEBUG" default="humanfriendly">
  Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.
</ParamField>

<ParamField body="--non-interactive">
  Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.
</ParamField>

**Example:**

```sh theme={"system"}
truss loops view
```

The command prints one row per run with the run ID, base model, run-level status, and creation time, ordered oldest first; pass `--reverse` to show the most recent run first.

***

## `logs`

Fetch logs for a Loops run. Identify the run with `--run-id`; by default this fetches the run's trainer logs, and `--sampler` fetches the paired sampler's logs instead. The two halves have separate log streams. Get run IDs from `truss loops view`.

```sh theme={"system"}
truss loops logs [OPTIONS]
```

### Options

<ParamField body="--run-id" type="TEXT">
  Loops run ID to fetch logs for.
</ParamField>

<ParamField body="--sampler">
  With --run-id, tail the paired sampler's logs instead of the run's trainer logs. The two halves have separate log streams.
</ParamField>

<ParamField body="--loops-deployment-id" type="TEXT" deprecated>
  Use --run-id to fetch the run's trainer logs; this will be removed in a future release.
</ParamField>

<ParamField body="--sampler-deployment-id" type="TEXT" deprecated>
  Use --run-id --sampler instead; this will be removed in a future release. Fetch logs from the sampler's inference deployment by ID.
</ParamField>

<ParamField body="--tail">
  Continue polling for new log lines until the deployment goes inactive (or Ctrl+C).
</ParamField>

<ParamField body="--remote" type="TEXT">
  Remote to use.
</ParamField>

<ParamField body="--log" type="humanfriendly | W | WARNING | I | INFO | D | DEBUG" default="humanfriendly">
  Customizes logging.
</ParamField>

<ParamField body="--non-interactive">
  Disables interactive prompts, use in CI / automated execution contexts.
</ParamField>

**Examples:**

```sh theme={"system"}
truss loops logs --run-id <run_id>
```

Stream the sampler's logs and keep polling until the deployment goes inactive:

```sh theme={"system"}
truss loops logs --run-id <run_id> --sampler --tail
```

The deprecated `--loops-deployment-id` and `--sampler-deployment-id` flags fetch logs by deployment ID instead; prefer `--run-id`.

***

## `usage`

Report Loops GPU capacity, one row per deployment (keyed by its run). Org-wide by default; pass `--mine` for just your own deployments (which drops the Owner column) or `--user` to filter to a single owner. Each row shows the trainer and sampler GPU allocations and statuses, and a summary line above the table aggregates GPUs in use vs. scaled to zero. Standalone samplers (no trainer) appear as sampler-only rows.

The report shows what each deployment is running on (instance types and statuses), not your organization's GPU quota.

By default the table lists only allocations holding live GPUs; the summary counts idle (scaled-to-zero) and terminal allocations, but the table hides them unless you pass `--all`.

```sh theme={"system"}
truss loops usage [OPTIONS]
```

### Options

<ParamField body="--remote" type="TEXT">
  Remote to use.
</ParamField>

<ParamField body="--mine">
  Show only your own Loops deployments (drops the Owner column).
</ParamField>

<ParamField body="--user" type="TEXT">
  Filter to Loops deployments owned by this email (looked up org-wide).
</ParamField>

<ParamField body="--all">
  Include deployments in terminal states (STOPPED, FAILED).
</ParamField>

<ParamField body="-o, --output-format" type="cli-table | json" default="cli-table">
  Output format: cli-table (default) or json.
</ParamField>

<ParamField body="--log" type="humanfriendly | W | WARNING | I | INFO | D | DEBUG" default="humanfriendly">
  Customizes logging.
</ParamField>

<ParamField body="--non-interactive">
  Disables interactive prompts, use in CI / automated execution contexts.
</ParamField>

**Example:**

```sh theme={"system"}
truss loops usage --mine
```

***

## `runs view`

<Warning>
  `truss loops runs view` is deprecated. Use [`truss loops view`](#view) instead.
</Warning>

List Loops runs visible to the caller. Both filters are optional and can be combined; omit both to list every run.

```sh theme={"system"}
truss loops runs view [OPTIONS]
```

### Options

<ParamField body="--run-id" type="TEXT">
  Filter to a specific run ID.
</ParamField>

<ParamField body="--base-model" type="TEXT">
  Filter runs by base model name.
</ParamField>

<ParamField body="-r, --reverse">
  Reverse the default order (oldest first) so the most recent run is shown first.
</ParamField>

<ParamField body="--remote" type="TEXT">
  Name of the remote in `.trussrc`.
</ParamField>

<ParamField body="--log" type="humanfriendly | W | WARNING | I | INFO | D | DEBUG" default="humanfriendly">
  Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.
</ParamField>

<ParamField body="--non-interactive">
  Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.
</ParamField>

**Example:**

List the most recent runs for a base model:

```sh theme={"system"}
truss loops runs view --base-model Qwen/Qwen3-8B --reverse
```

***

## `samplers view`

<Warning>
  `truss loops samplers view` is deprecated. Use [`truss loops usage`](#usage) instead.
</Warning>

List Loops samplers visible to the caller.

```sh theme={"system"}
truss loops samplers view [OPTIONS]
```

### Options

<ParamField body="-r, --reverse">
  Reverse the default order (oldest first) so the most recent sampler is shown first.
</ParamField>

<ParamField body="--remote" type="TEXT">
  Name of the remote in `.trussrc`.
</ParamField>

<ParamField body="--log" type="humanfriendly | W | WARNING | I | INFO | D | DEBUG" default="humanfriendly">
  Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.
</ParamField>

<ParamField body="--non-interactive">
  Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.
</ParamField>

**Example:**

```sh theme={"system"}
truss loops samplers view --reverse
```

***

## `checkpoints view`

List checkpoints for a Loops run. Identify the run with `--run-id`, or pass `--base-model` to pick the most recent run for that base model. The two filters are mutually exclusive.

```sh theme={"system"}
truss loops checkpoints view [OPTIONS]
```

### Options

<ParamField body="--run-id" type="TEXT">
  Loops run ID to list checkpoints for. Mutually exclusive with `--base-model`.
</ParamField>

<ParamField body="--base-model" type="TEXT">
  Base model name. Resolves to the most recent Loops run for that model. Mutually exclusive with `--run-id`.
</ParamField>

<ParamField body="--sort" type="checkpoint-id | size | created | type" default="created">
  Sort checkpoints by checkpoint ID, creation time, size, or type.
</ParamField>

<ParamField body="--order" type="asc | desc" default="asc">
  Sort order.
</ParamField>

<ParamField body="-o, --output-format" type="cli-table | csv | json" default="cli-table">
  Output format.
</ParamField>

<ParamField body="--remote" type="TEXT">
  Name of the remote in `.trussrc`.
</ParamField>

<ParamField body="--log" type="humanfriendly | W | WARNING | I | INFO | D | DEBUG" default="humanfriendly">
  Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.
</ParamField>

<ParamField body="--non-interactive">
  Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.
</ParamField>

**Examples:**

List checkpoints for the most recent run of a base model:

```sh theme={"system"}
truss loops checkpoints view --base-model Qwen/Qwen3-8B
```

Get the largest checkpoints first, as JSON:

```sh theme={"system"}
truss loops checkpoints view --run-id <run_id> --sort size --order desc -o json
```

***

## `checkpoints deploy`

Deploy checkpoints from a Loops run as a vLLM-backed inference deployment. Identify checkpoints by name with `--checkpoints` (requires `--run-id`, since names are scoped per run) or by globally unique ID with `--checkpoint-ids`, or pass just `--run-id` to pick interactively.

```sh theme={"system"}
truss loops checkpoints deploy [OPTIONS]
```

### Options

<ParamField body="--run-id" type="TEXT">
  Loops run ID. Opens an interactive picker so you can choose checkpoints from the run. Cannot be combined with `--checkpoint-ids`.
</ParamField>

<ParamField body="--checkpoints" type="TEXT">
  Comma-separated Loops checkpoint names (e.g. step-50,step-100). Requires --run-id, since names are scoped per run. Bypasses the interactive picker. Use `truss loops checkpoints view` to find names.
</ParamField>

<ParamField body="--checkpoint-ids" type="TEXT">
  Comma-separated Loops checkpoint IDs (for example, `vL3pQrS8,wK4tUvW9`). Bypasses the interactive picker. Use `truss loops checkpoints view` to find IDs. Cannot be combined with `--run-id` or `--config`.
</ParamField>

<ParamField body="--config" type="TEXT">
  Path to a Python file that defines a `DeployCheckpointsConfig`. The config must populate `checkpoint_details.loops_checkpoint_ids`. Cannot be combined with `--checkpoint-ids`.
</ParamField>

<ParamField body="--dry-run">
  Render the generated truss config to stdout without deploying.
</ParamField>

<ParamField body="--remote" type="TEXT">
  Name of the remote in `.trussrc`.
</ParamField>

<ParamField body="--log" type="humanfriendly | W | WARNING | I | INFO | D | DEBUG" default="humanfriendly">
  Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.
</ParamField>

<ParamField body="--non-interactive">
  Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.
</ParamField>

**Examples:**

Pick checkpoints interactively from a run:

```sh theme={"system"}
truss loops checkpoints deploy --run-id <run_id>
```

Deploy checkpoints by name from a run:

```sh theme={"system"}
truss loops checkpoints deploy --run-id <run_id> --checkpoints step-50,step-100
```

Deploy specific checkpoint IDs:

```sh theme={"system"}
truss loops checkpoints deploy --checkpoint-ids vL3pQrS8,wK4tUvW9
```

Render the generated config without deploying:

```sh theme={"system"}
truss loops checkpoints deploy --run-id <run_id> --dry-run
```

The interactive picker only lists deployable (sampler-target) checkpoints. Trainer-target checkpoints hold training state and can't be served, so they're excluded. If a run has no deployable checkpoints, the command exits with an error.

## Related

* [Loops concepts](/loops/concepts): How sessions, runs, samplers, and checkpoints fit together.
* [Loops supported models](/loops/supported-models): Base models you can pass to `truss loops push`.
* [Training SDK reference](/reference/sdk/training): `CheckpointList` and `DeployCheckpointsConfig` Python types used with `--config`.