> ## 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](https://docs.baseten.co/loops/concepts.md) deployment lifecycle. Use it to run a Loops client on Baseten, push a run for a base model, inspect runs, report GPU usage, and deploy checkpoints.

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

| Command | Description |
| - | - |
| [`exec`](#exec) | Run a Loops client in a Baseten training job. |
| [`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. |

***

## `exec`

Run a Loops client from your current directory in a Baseten training job. Truss uploads the directory and runs the command that follows `--`. The job has 16 CPUs and 64 GiB of memory by default, and you can request a GPU with `--accelerator`.

Truss provides `BASETEN_API_KEY` from a per-team secret unless you set the variable with `--env` or `--secret`. Pass `--no-api-key` to run without a Baseten credential. The command returns after launching the job by default; pass `--tail` to stream its status and logs.

```sh theme={"system"}
truss loops exec [OPTIONS] -- START_COMMAND...
```

### Arguments

**START\_COMMAND** `TEXT` *required*

Command to run in the training job. Place it after `--`. Truss passes the command through unchanged and runs it after the job's setup steps.

### Options

**--accelerator** `T4 | L4 | A10G | V100 | A100 | A100_40GB | H100 | H200 | H100_40GB | B200 | L40S | RTX_PRO_6000 | B300 | GB300`

GPU accelerator type. Omit for a CPU-only job (the default).

**--gpu-count** `INTEGER RANGE`

Number of GPUs (1-8, default: 1). Requires --accelerator.

**--cpu-count** `INTEGER RANGE` (default: 16)

Number of CPUs to request.

**--memory** `TEXT` (default: 64Gi)

Memory to request (e.g. 8Gi).

**--project-name** `TEXT`

Training project name (default: the name of the current directory).

**--image** `TEXT`

Custom Docker base image.

**--workspace-root** `TEXT`

Directory to upload instead of just the current directory. Must be a parent of the current directory.

**--exclude-dir** `TEXT`

Top-level directory of the workspace root to leave out of the upload. Repeatable.

**--external-dir** `TEXT`

Directory outside the workspace root to include in the upload. Repeatable.

**--env** `TEXT`

Environment variable for the job as KEY=VALUE. Repeatable.

**--secret** `TEXT`

Environment variable sourced from a Baseten workspace secret, as KEY=SECRET\_NAME. Create secrets at [https://app.baseten.co/settings/secrets](https://app.baseten.co/settings/secrets). Repeatable.

**-o, --output-format** `text | json` (default: text)

Output format. `json` emits structured JSON to stdout and sends progress and logs to stderr. Default is `text`.

**--api-key / --no-api-key**

Set BASETEN\_API\_KEY in the job from a per-team secret, creating the key on first use. Pass --no-api-key for a job that should carry no credential.

**--ssh / --no-ssh**

Enable on-demand SSH access. Pass --no-ssh to run without an interactive session.

**--with-uv**

Make uv available in the job image. Your command should invoke uv itself, e.g. `truss loops exec --with-uv -- uv run python my_client.py`.

**--remote** `TEXT`

Name of the remote in `.trussrc` to use.

**--team** `TEXT`

Name of the team that owns the training project. If not specified, Truss uses the team configured for the remote in `.trussrc`.

**--tail / --no-tail**

Stream status + logs after push instead of returning immediately. With --tail, exec exits non-zero if the job fails.

**--log** `humanfriendly | W | WARNING | I | INFO | D | DEBUG` (default: humanfriendly)

Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.

**--non-interactive**

Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.

**Examples:**

Run a Python client from the current directory:

```sh theme={"system"}
truss loops exec -- python client.py
```

Make uv available in the job and stream logs until it finishes:

```sh theme={"system"}
truss loops exec --with-uv --tail -- uv run python client.py
```

***

## `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.

SDK scripts create their own runs. To check access without provisioning GPUs, see [Check model access](https://docs.baseten.co/troubleshooting/loops.md#check-model-access).

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

### Arguments

**BASE\_MODEL** `TEXT` *required*

Hugging Face model ID for the base model (for example, `Qwen/Qwen3-8B`).

### Options

**--project-id** `TEXT`

Training project ID to associate the deployment with.

**--replicas** `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.

**--sampler-num-replicas** `INTEGER RANGE`

Number of replicas for the run's paired sampler, applied as both its minimum and maximum. Must be at least 1. If omitted, the sampler uses the platform default. See [Samplers](https://docs.baseten.co/loops/concepts.md#samplers).

**--remote** `TEXT`

Name of the remote in `.trussrc` to deploy to.

**--log** `humanfriendly | W | WARNING | I | INFO | D | DEBUG` (default: humanfriendly)

Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.

**--non-interactive**

Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.

**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

**DEPLOYMENT\_ID** `TEXT` *deprecated*

Passing a Loops deployment ID as a positional argument is deprecated; use `--run-id` instead.

### Options

**--run-id** `TEXT`

Loops run ID to deactivate.

**--remote** `TEXT`

Name of the remote in `.trussrc`.

**-y, --yes**

Skip the confirmation prompt.

**--log** `humanfriendly | W | WARNING | I | INFO | D | DEBUG` (default: humanfriendly)

Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.

**--non-interactive**

Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.

**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

**--remote** `TEXT`

Name of the remote in `.trussrc`.

**--all**

Include inactive runs.

**--org**

List every Loops run in your organization (with its owner), not just your own.

**-r, --reverse**

Reverse the default order (oldest first) so the most recent run is shown first.

**-o, --output-format** `cli-table | json` (default: cli-table)

Output format: cli-table (default) or json.

**--log** `humanfriendly | W | WARNING | I | INFO | D | DEBUG` (default: humanfriendly)

Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.

**--non-interactive**

Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.

**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

**--run-id** `TEXT`

Loops run ID to fetch logs for.

**--sampler**

With --run-id, tail the paired sampler's logs instead of the run's trainer logs. The two halves have separate log streams.

**--loops-deployment-id** `TEXT` *deprecated*

Use --run-id to fetch the run's trainer logs; this will be removed in a future release.

**--sampler-deployment-id** `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.

**--tail**

Continue polling for new log lines until the deployment goes inactive (or Ctrl+C).

**--remote** `TEXT`

Remote to use.

**--log** `humanfriendly | W | WARNING | I | INFO | D | DEBUG` (default: humanfriendly)

Customizes logging.

**--non-interactive**

Disables interactive prompts, use in CI / automated execution contexts.

**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

**--remote** `TEXT`

Remote to use.

**--mine**

Show only your own Loops deployments (drops the Owner column).

**--user** `TEXT`

Filter to Loops deployments owned by this email (looked up org-wide).

**--all**

Include deployments in terminal states (STOPPED, FAILED).

**-o, --output-format** `cli-table | json` (default: cli-table)

Output format: cli-table (default) or json.

**--log** `humanfriendly | W | WARNING | I | INFO | D | DEBUG` (default: humanfriendly)

Customizes logging.

**--non-interactive**

Disables interactive prompts, use in CI / automated execution contexts.

**Example:**

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

***

## `runs view`

> [!WARNING]
>
> `truss loops runs view` is deprecated. Use [`truss loops view`](#view) instead.

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

**--run-id** `TEXT`

Filter to a specific run ID.

**--base-model** `TEXT`

Filter runs by base model name.

**-r, --reverse**

Reverse the default order (oldest first) so the most recent run is shown first.

**--remote** `TEXT`

Name of the remote in `.trussrc`.

**--log** `humanfriendly | W | WARNING | I | INFO | D | DEBUG` (default: humanfriendly)

Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.

**--non-interactive**

Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.

**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.

List Loops samplers visible to the caller.

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

### Options

**-r, --reverse**

Reverse the default order (oldest first) so the most recent sampler is shown first.

**--remote** `TEXT`

Name of the remote in `.trussrc`.

**--log** `humanfriendly | W | WARNING | I | INFO | D | DEBUG` (default: humanfriendly)

Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.

**--non-interactive**

Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.

**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

**--run-id** `TEXT`

Loops run ID to list checkpoints for. Mutually exclusive with `--base-model`.

**--base-model** `TEXT`

Base model name. Resolves to the most recent Loops run for that model. Mutually exclusive with `--run-id`.

**--sort** `checkpoint-id | size | created | type` (default: created)

Sort checkpoints by checkpoint ID, creation time, size, or type.

**--order** `asc | desc` (default: asc)

Sort order.

**-o, --output-format** `cli-table | csv | json` (default: cli-table)

Output format.

**--remote** `TEXT`

Name of the remote in `.trussrc`.

**--log** `humanfriendly | W | WARNING | I | INFO | D | DEBUG` (default: humanfriendly)

Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.

**--non-interactive**

Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.

**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

**--run-id** `TEXT`

Loops run ID. Opens an interactive picker so you can choose checkpoints from the run. Cannot be combined with `--checkpoint-ids`.

**--checkpoints** `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.

**--checkpoint-ids** `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`.

**--config** `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`.

**--dry-run**

Render the generated truss config to stdout without deploying.

**--remote** `TEXT`

Name of the remote in `.trussrc`.

**--log** `humanfriendly | W | WARNING | I | INFO | D | DEBUG` (default: humanfriendly)

Logging verbosity. `humanfriendly` (default) is pretty-printed; `INFO`, `DEBUG`, `WARNING` produce structured logs.

**--non-interactive**

Disable interactive prompts. Use in CI/automated contexts where stdin isn't a TTY.

**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](https://docs.baseten.co/loops/concepts.md): How sessions, runs, samplers, and checkpoints fit together.
* [Loops supported models](https://docs.baseten.co/loops/supported-models.md): Base models you can pass to `truss loops push`.
* [Training SDK reference](https://docs.baseten.co/reference/sdk/training.md): `CheckpointList` and `DeployCheckpointsConfig` Python types used with `--config`.
