Skip to main content
Run a Loops client as a managed training job, inspect its usage, and manage runs and the checkpoints they save. For Truss Loops commands, see the Truss CLI reference or run baseten truss loops --help with your Baseten CLI credentials.

​
exec

Package the directory selected by --dir and run a Loops client as a managed training job. Pass the command to run after --. Everything after the delimiter is preserved verbatim. Baseten credentials are forwarded to Truss from the selected CLI profile. By default, Truss makes BASETEN_API_KEY available to the job from a per-team workspace secret, creating the credential and secret on first use when necessary. Pass --no-api-key to disable this behavior, or set BASETEN_API_KEY explicitly with --env or --secret. Pass --no-ssh to submit a job without an interactive SSH session. Otherwise, Training SSH must be enabled for the workspace. The command returns once the job is created. Pass --tail to stream logs to stderr; the job result stays on stdout. With --tail, the command exits nonzero if the job fails to deploy or execute. Ctrl+C stops watching without stopping the job. Resume with baseten train job logs --job-id <job-id> --tail.

​
Options

​
TEXT
GPU accelerator type. Omit for a CPU-only job. Supported hardware is documented at https://docs.baseten.co/training/concepts/basics.
​
INTEGER
default:"16"
Number of CPUs to request.
​
TEXT
required
Directory to upload and run the command from. Required; use ’.’ to select the current directory.
​
TEXT (repeatable)
Environment variable for the job as KEY=VALUE. Repeatable.
​
TEXT (repeatable)
Top-level directory of the workspace root to leave out of the upload. Repeatable.
​
TEXT (repeatable)
Directory outside --dir to include in the upload. Relative paths resolve from the caller’s current directory. Repeatable.
​
INTEGER
Number of GPUs, from 1 to 8. Requires --accelerator.
​
TEXT
Custom Docker base image.
​
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
​
TEXT
default:"64Gi"
Memory to request, for example 8Gi.
​
BOOL
Do not provision BASETEN_API_KEY in the job from a per-team workspace secret.
​
BOOL
Do not create an interactive SSH session. The job can run without Training SSH enabled for the workspace.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Training project name. Defaults to the selected directory’s name.
​
TEXT (repeatable)
Environment variable sourced from a Baseten workspace secret as KEY=SECRET_NAME. Repeatable.
​
BOOL
Stream job logs to stderr until the job stops or you press Ctrl-C. Cannot be combined with --truss-no-forward-auth.
​
TEXT
Team name that owns the training project.
​
BOOL
Make uv available in the job image. The start command must invoke uv itself.
​
TEXT
Run this truss executable instead of fetching one with uv, e.g. a virtualenv’s bin/truss. A value with no path separator is looked up on PATH, so ‘--truss-executable truss’ runs the truss you installed. Defaults to BASETEN_TRUSS_EXECUTABLE.
​
BOOL
Do not forward this CLI’s credentials to truss, leaving it to resolve a remote from your trussrc. Old truss versions ignore forwarded credentials and use the trussrc regardless.
​
TEXT
Version of truss to fetch and run with ‘uv tool run’, e.g. 0.18.26. Defaults to BASETEN_TRUSS_VERSION, or the latest release. Mutually exclusive with --truss-executable.
​
BOOL
Enable verbose logging

​
Examples

Run a Python Loops client with uv
Run a client and follow its logs
Run a client on one H100 using a CUDA image with Python

​
Filter output with --jq

Print the created job ID

​
Output

Text mode (--output text): The created job’s ID, SSH hostname when enabled, and a command to follow its logs. JSON mode (--output json): payload type cmd.LoopsExecResult. The job ID, project, SSH hostname, start command, environment variable names, compute configuration, and job response.

​
usage

Report Loops GPU capacity, one row per trainer deployment plus a row for each standalone sampler. A summary above the table totals the GPUs in use and scaled to zero. Rows holding no live GPUs (scaled to zero, or in a terminal state) are counted in the summary but hidden unless you pass --all.

​
Options

​
BOOL
Include allocations holding no live GPUs (scaled to zero, or in a terminal state).
​
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
​
BOOL
Report usage across the organization, with each allocation’s owner, instead of only your own.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Only report allocations owned by this email. Implies --org.
​
BOOL
Enable verbose logging

​
Examples

Report your own Loops GPU usage
Report GPU usage across the organization, including idle allocations
Report GPU usage for one owner

​
Filter output with --jq

Print the total trainer GPUs in use

​
Output

Text mode (--output text): A summary line of trainer and sampler GPU totals, then a table with columns: RUN, OWNER (with --org), BASE MODEL, TRAINER GPU, TRAINER STATUS, SAMPLER GPU, SAMPLER STATUS, CREATED. JSON mode (--output json): payload type cmd.LoopsUsageResult. An object with the GPU summary and one entry per row, each carrying the trainer and sampler allocation and status.

​
run

A run trains a base model and pairs it with a sampler. Create, inspect, and deactivate runs.

​
create

Create a Loops session, a run for the given base model, and the run’s paired sampler. Returns as soon as the resources are provisioned. Both halves finish coming up in the background; poll with ‘baseten loops run describe’ or watch ‘baseten loops run logs’.

​
Options

​
TEXT
required
HuggingFace ID of the base model to fine-tune (for example ‘Qwen/Qwen3-8B’). Supported models are listed at https://docs.baseten.co/loops/supported-models.
​
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
​
TEXT
Display name for the run. Defaults to the base model.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
INTEGER
Number of data-parallel trainer replicas. The trainer deployment runs this many copies of the model’s preset node group, so --replicas 4 on a 4-node preset provisions 16 nodes. Defaults to 1.
​
TEXT
Team name or ID that owns the run’s infrastructure. Defaults to the organization’s default team. Run ‘baseten org team list’ to see teams.
​
BOOL
Enable verbose logging

​
Examples

Create a run for a base model
Create a named run with four data-parallel trainer replicas

​
Filter output with --jq

Print just the new run’s ID

​
Output

Text mode (--output text): On success, prints the new run’s ID and base model to stderr; no stdout output. JSON mode (--output json): payload type managementapi.LoopsRun. The created run, including its paired sampler.

​
list

List Loops runs, newest first. Lists your own runs; pass --org to list every run in the organization, which adds an Owner column. Inactive runs are hidden unless you pass --all.

​
Options

​
BOOL
Include inactive runs.
​
TEXT
Only list runs of this base model.
​
TEXT
default:"desc"
Sort order by creation time: ‘desc’ (newest first) or ‘asc’ (oldest first).One of: asc, desc
​
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
​
BOOL
List every run in the organization, with its owner, instead of only your own.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
BOOL
Enable verbose logging

​
Examples

List your active runs
List every run in the organization, including inactive ones
List runs for one base model, oldest first

​
Filter output with --jq

Print just the run IDs

​
Output

Text mode (--output text): Table with columns: ID, OWNER (with --org), BASE MODEL, STATUS, CREATED. When no runs match, prints “No Loops runs found.” to stderr. JSON mode (--output json): payload type managementapi.ListLoopsRunsResponse.

​
describe

Describe a Loops run by ID, including its paired sampler.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
required
ID of the Loops run.
​
BOOL
Enable verbose logging

​
Examples

Describe a run by ID

​
Filter output with --jq

Print the run’s sampler base URL

​
Output

Text mode (--output text): Field-per-line summary of the run, followed by its sampler when one exists. JSON mode (--output json): payload type managementapi.LoopsRun.

​
deactivate

Deactivate a Loops run, tearing down both the run and its paired sampler. Saved checkpoints remain accessible. Prompts for yes/no confirmation. Pass --yes to skip the prompt. When stdin is not a terminal, --yes is required.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
required
ID of the Loops run.
​
BOOL
Skip the interactive confirmation prompt. Required when stdin is not a terminal.
​
BOOL
Enable verbose logging

​
Examples

Deactivate a run without the confirmation prompt

​
Filter output with --jq

Print the deactivated run’s base model

​
Output

Text mode (--output text): On success, prints “Deactivated Loops run id” to stderr; no stdout output. JSON mode (--output json): payload type managementapi.DeactivateLoopsRunResponse.

​
logs

Fetch logs for a Loops run. By default returns the run’s trainer logs; pass --sampler for the paired sampler’s logs instead, which are a separate stream. By default returns up to --limit lines from the last 30 minutes, newest first. Use --start/--end or --since to scope the window (max 7 days). Use --tail to stream live logs until the run stops producing them or you interrupt with Ctrl-C. For machine-readable streaming, prefer --output jsonl over --output json.

​
Options

​
TEXT
End of the log time range. Accepts ISO 8601; values without a timezone designator are interpreted in the local timezone. Default is now. Window must be at most 7 days.
​
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
​
INTEGER
default:"5000"
Maximum number of log lines to return, paging backward from the end of the window. Use 0 for no limit (every log line in the window). Not applicable with --tail.
​
TEXT
Only return logs at or above this severity level.One of: debug, info, warning, error
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
required
ID of the Loops run.
​
BOOL
Fetch the paired sampler’s logs instead of the run’s trainer logs.
​
TEXT
Shortcut for fetching logs from a relative time ago until now. Accepts a duration (e.g. ‘30m’, ‘1h30m’) or ‘Nd’ (e.g. ‘3d’). Maximum ‘7d’. Mutually exclusive with --start and --end.
​
TEXT
Start of the log time range. Accepts ISO 8601 (e.g. ‘2026-05-14’, ‘2026-05-14T12:00:00’, ‘2026-05-14T12:00:00Z’). Values without a timezone designator are interpreted in the local timezone. Default is 30 minutes before the end. Window must be at most 7 days.
​
BOOL
Stream new logs as they arrive until the run stops producing them or you interrupt with Ctrl-C. Cannot be combined with the time-range or filter flags. For machine-readable streaming, prefer --output jsonl over --output json.
​
BOOL
Enable verbose logging

​
Examples

Print a run’s trainer logs over the last hour
Tail the paired sampler’s logs

​
Filter output with --jq

Stream just the log messages as a JSONL stream

​
Output

Text mode (--output text): One line per log record: “[YYYY-MM-DD HH:MM:SS]: (replica) message”. JSON mode (--output json): payload type managementapi.Log.

​
checkpoint

Checkpoints are saved while a Loops run trains. List them, get download URLs for their files, and deploy them as a model served by vLLM.

​
list

List checkpoints for a Loops run, newest first. Identify the run with --run-id, or pass --base-model to list checkpoints across all of your runs of that base model.

​
Options

​
TEXT
List checkpoints across your runs of this base model.Mutually exclusive with other flags in group loops-checkpoint-scope.
​
TEXT
default:"desc"
Sort order by creation time: ‘desc’ (newest first) or ‘asc’ (oldest first).One of: asc, desc
​
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
List checkpoints saved by this run.Mutually exclusive with other flags in group loops-checkpoint-scope.
​
BOOL
Enable verbose logging

​
Examples

List a run’s checkpoints
List every checkpoint for a base model, oldest first

​
Filter output with --jq

Print the deployable checkpoint names

​
Output

Text mode (--output text): Table with columns: ID, NAME, RUN, TARGET, TYPE, SIZE, CREATED. When no checkpoints match, prints “No Loops checkpoints found.” to stderr. JSON mode (--output json): payload type managementapi.ListLoopsCheckpointsResponse.

​
files

List presigned download URLs for the files under a Loops checkpoint. The URLs are short-lived. Use ‘baseten loops checkpoint list’ to find checkpoint IDs. For machine-readable streaming, prefer --output jsonl over --output json.

​
Options

​
TEXT
required
ID of the Loops checkpoint. Run ‘baseten loops checkpoint list’ to see checkpoints.
​
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
BOOL
Enable verbose logging

​
Examples

List a checkpoint’s files

​
Filter output with --jq

Print just the download URLs

​
Output

Text mode (--output text): Table with columns: NAME, SIZE, URL. JSON mode (--output json): payload type managementapi.CheckpointFile.

​
deploy

Deploy checkpoints saved by a Loops run as a model served by vLLM. Name the checkpoints with --checkpoint (which needs --run-id, since names are scoped to a run) or with --checkpoint-id, or pass none of them to choose interactively. Requests then select a checkpoint by name through the model parameter, so one deployment serves them all. Pass --config for a repeatable deploy: it is a Python file defining a DeployCheckpointsConfig, so it is executed rather than read.

​
Options

​
TEXT (repeatable)
Name of a checkpoint to deploy, for example ‘step-50’. Requires --run-id, since names are scoped to a run. Cannot be combined with --checkpoint-id or --config. Repeatable.
​
TEXT (repeatable)
ID of a checkpoint to deploy. Cannot be combined with --run-id, --checkpoint, or --config. Repeatable. Run ‘baseten loops checkpoint list’ to see checkpoints.
​
TEXT
Python file defining a DeployCheckpointsConfig: which checkpoints deploy and the model that serves them. Cannot be combined with --checkpoint or --checkpoint-id. The type is documented at https://docs.baseten.co/reference/sdk/training#deploycheckpointsconfig.
​
BOOL
Print the generated model config without deploying anything.
​
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Loops run whose checkpoints are deployed. Cannot be combined with --checkpoint-id.
​
TEXT
Run this truss executable instead of fetching one with uv, e.g. a virtualenv’s bin/truss. A value with no path separator is looked up on PATH, so ‘--truss-executable truss’ runs the truss you installed. Defaults to BASETEN_TRUSS_EXECUTABLE.
​
BOOL
Do not forward this CLI’s credentials to truss, leaving it to resolve a remote from your trussrc. Old truss versions ignore forwarded credentials and use the trussrc regardless.
​
TEXT
Version of truss to fetch and run with ‘uv tool run’, e.g. 0.18.26. Defaults to BASETEN_TRUSS_VERSION, or the latest release. Mutually exclusive with --truss-executable.
​
BOOL
Enable verbose logging

​
Examples

Deploy two checkpoints of a run by name
Deploy a checkpoint by ID, choosing the rest interactively

​
Output

Text mode (--output text): The new model and deployment IDs with links to the deployment’s logs, and how to name a checkpoint in a request. With --dry-run, the generated model config instead. JSON mode (--output json): payload type cmd.TrussDelegatedResult. Under --output json the text output goes to stderr and stdout is an empty object: this command reports nothing structured yet.