Training CLI reference

The truss train command provides subcommands for managing the full training job lifecycle.

truss train [COMMAND] [OPTIONS]

init

Initialize a training project from templates or create an empty project.

truss train init [OPTIONS]

Options

List all available examples.

TEXT

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

Initialize a project from a template:

truss train init --examples qwen3-8b-lora-dpo-trl

Initialize multiple templates:

truss train init --examples qwen3-8b-lora-dpo-trl,qwen3-8b-lora-verl

List available templates:

truss train init --list-examples

Create an empty training project:

truss train init

push

Submit and run a training job.

truss train push [OPTIONS] CONFIG

Arguments

string

required

Path to the training configuration file (for example, config.py).

Options

TEXT

Remote to use.

Tail for status + logs after push.

TEXT

Name of the training job.

TEXT

Team name for the training project

The --team flag is only available if your organization has teams enabled. Contact us to enable teams, or see Teams for more information.

on_startup | on_failure | on_demand

Interactive session trigger mode

INTEGER

Interactive session timeout in minutes

TEXT

Accelerator type and count (e.g., H200:8)

INTEGER

Number of compute nodes

TEXT

Entrypoint command.

INTEGER

Job priority (higher values run first when capacity frees up).

Run the job on interruptible spot capacity, overriding availability_model in the compute config. Spot jobs can be preempted at any time; you’re responsible for checkpointing your own progress. See Checkpoints.

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

Submit a training job:

truss train push config.py

Submit and stream logs:

truss train push config.py --tail

Submit to a specific team:

truss train push config.py --team my-team-name

Submit with a custom job name:

truss train push config.py --job-name fine-tune-v1

logs

Fetch and stream logs from a training job.

truss train logs [OPTIONS]

Options

TEXT

Remote to use.

TEXT

Project ID.

TEXT

Project name or project id.

TEXT

Job ID.

Tail for ongoing logs.

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

Stream logs for a specific job:

truss train logs --job-id abc123 --tail

View logs for a job without streaming:

truss train logs --job-id abc123

metrics

View real-time metrics for a training job including CPU, GPU, and storage usage.

truss train metrics [OPTIONS]

Options

TEXT

Project ID.

TEXT

Project name or project id.

TEXT

Job ID.

TEXT

Remote to use.

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

View metrics for a specific job:

truss train metrics --job-id abc123

view

List training projects and jobs, or view details for a specific job. This command lists jobs in the TRAINING_JOB_PENDING state (waiting for GPU capacity) alongside other active jobs.

truss train view [OPTIONS]

Options

TEXT

View training jobs for a project.

TEXT

Project name or project id.

TEXT

View a specific training job.

TEXT

Remote to use.

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

List all training projects:

truss train view

View jobs in a specific project:

truss train view --project my-project

View details for a specific job:

truss train view --job-id abc123

stop

Stop a queued, running, or pending training job.

truss train stop [OPTIONS]

Options

TEXT

Project ID.

TEXT

Project name or project id.

TEXT

Job ID.

Stop all running jobs.

TEXT

Remote to use.

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

Stop a specific job:

truss train stop --job-id abc123

Stop all queued or running jobs:

truss train stop --all

update

Update fields on an existing training job, such as a pending job’s queue priority. Provide at least one field to update.

truss train update [OPTIONS]

Options

TEXT

Job ID of the training job.

INTEGER

New queue priority. Higher values are dequeued first. Only PENDING jobs can have their priority changed.

TEXT

Remote to use.

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

Update the priority of a pending job:

truss train update --job-id abc123 --priority 10

recreate

Recreate an existing training job with the same configuration.

truss train recreate [OPTIONS]

Options

TEXT

Job ID of Training Job to recreate

TEXT

Remote to use.

Tail for status + logs after recreation.

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

Recreate a specific job:

truss train recreate --job-id abc123

Recreate and stream logs:

truss train recreate --job-id abc123 --tail

download

Download training job artifacts to your local machine.

truss train download [OPTIONS]

Options

TEXT

Job ID.

TEXT

Remote to use.

Examples

Download artifacts to current directory:

truss train download --job-id abc123

Download to a specific directory:

truss train download --job-id abc123 --target-directory ./downloads

Download without extracting:

truss train download --job-id abc123 --no-unzip

deploy_checkpoints

Deploy a trained model checkpoint to Baseten’s inference platform.

truss train deploy_checkpoints [OPTIONS]

Options

TEXT

Project ID.

TEXT

Project name or project id.

TEXT

Job ID.

TEXT

path to a python file that defines a DeployCheckpointsConfig

Generate a truss config without deploying

TEXT

Path to output the truss config to. If not provided, will output to truss_configs/model_version_namemodel_version_id or truss_configs/dry_runtimestamp if dry run.

TEXT

Remote to use.

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

Deploy checkpoints interactively:

truss train deploy_checkpoints

Deploy checkpoints from a specific job:

truss train deploy_checkpoints --job-id abc123

Preview deployment without deploying:

truss train deploy_checkpoints --job-id abc123 --dry-run

Output

After a successful deployment, the command prints a labeled block with the Model ID, Deployment ID, and a link to the deployment’s logs page.

get_checkpoint_urls

Get presigned URLs for checkpoint artifacts.

truss train get_checkpoint_urls [OPTIONS]

Options

TEXT

Job ID.

TEXT

Remote to use.

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

Get checkpoint URLs for a job:

truss train get_checkpoint_urls --job-id abc123

checkpoints list

List and interactively explore checkpoints for a training job.

truss train checkpoints list [OPTIONS]

Options

TEXT

Remote to use.

TEXT

Project ID.

TEXT

Project name or project id.

TEXT

Job ID.

TEXT

Jump directly into a specific checkpoint’s files.

checkpoint-id | size | created | type

default:"created"

Sort checkpoints by checkpoint-id, size, created date, or type.

asc | desc

default:"asc"

Sort order: ascending or descending.

cli-table | csv | json

default:"cli-table"

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

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Interactive mode

When using the default cli-table format in an interactive terminal, the command launches a checkpoint explorer:

Checkpoint picker: fuzzy-search and select a checkpoint from the list.
File explorer: navigate the checkpoint’s directory tree. Press → or Enter to open a directory or view a file. Press ← to go back. Press Ctrl-C to quit.

For .safetensors files, the explorer displays a tensor summary (layer names, dtypes, shapes, and parameter counts) instead of raw binary content. Text files display with syntax highlighting based on their file extension (for example, .json, .py, .yaml, .toml), falling back to plain text for unrecognized types.

Examples

List checkpoints for the most recent job:

truss train checkpoints list

List checkpoints for a specific job:

truss train checkpoints list --job-id abc123

Jump directly into a checkpoint’s files:

truss train checkpoints list --job-id abc123 --checkpoint-name ckpt-001

Export checkpoint list as JSON:

truss train checkpoints list --job-id abc123 --output-format json

Sort by size descending:

truss train checkpoints list --job-id abc123 --sort size --order desc

cache summarize

View a summary of the training cache for a project.

truss train cache summarize [OPTIONS] PROJECT

Arguments

string

required

Project name or project ID.

Options

TEXT

Remote to use.

filepath | size | modified | type | permissions

default:"filepath"

Sort files by filepath, size, modified date, file type, or permissions.

asc | desc

default:"asc"

Sort order: ascending or descending.

cli-table | csv | json

default:"cli-table"

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

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

View cache summary:

truss train cache summarize my-project

Sort by size descending:

truss train cache summarize my-project --sort size --order desc

Export as JSON:

truss train cache summarize my-project --output-format json

isession

View or update interactive session details for a training job, including auth codes and connection status.

truss train isession [OPTIONS]

Options

TEXT

Job ID of the training job.

TEXT

Remote to use.

INTEGER

Minutes to extend the session timeout by

on_startup | on_failure | on_demand

Change the session trigger (cannot be changed on on_startup sessions)

table | json

default:"table"

Output format (default: table)

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

View session details for a job:

truss train isession --job-id abc123

Extend session timeout:

truss train isession --job-id abc123 --update-timeout 60

Output as JSON:

truss train isession --job-id abc123 --format json

update_session

Update the interactive session configuration on a running training job. At least one of --trigger or --timeout-minutes must be provided.

truss train update_session [OPTIONS] JOB_ID

Arguments

string

required

Job ID of the training job to update.

Options

on_startup | on_failure | on_demand

When to create the interactive session: ‘on_startup’ creates on job start, ‘on_failure’ creates on job failure, ‘on_demand’ allows manual session creation.

INTEGER

Number of minutes before the interactive session times out.

TEXT

Remote to use.

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

Change the session trigger:

truss train update_session abc123 --trigger on_startup

Update the session timeout:

truss train update_session abc123 --timeout-minutes 120

truss train update_session requires API support that may not be available in all environments. If you receive a 404 error, set the trigger mode at push time using --interactive on_startup or --interactive on_failure instead.

workstation

Spin up an SSH workstation on Baseten training infrastructure.

truss train workstation [OPTIONS]

Options

T4 | L4 | A10G | V100 | A100 | A100_40GB | H100 | H200 | H100_40GB | B200 | L40S | RTX_PRO_6000 | B300 | GB300

default:"H100"

GPU type for the workstation (default: H100).

INTEGER RANGE

Number of GPUs for a single-node workstation (1-8, default: 1). Mutually exclusive with --node-count.

TEXT

Name of the training project that owns the workstation. Defaults to workstation-\{accelerator}, for example workstation-H100.

INTEGER RANGE

Number of full nodes to provision, each using all of its GPUs. Values above 1 bootstrap a Slurm cluster across the nodes. Mutually exclusive with --gpu-count.

See Slurm workstations for the cluster topology, verification steps, and how to launch distributed work.

slurm

default:"slurm"

Orchestrator bootstrapped across multi-node workstations. slurm is the only supported value. Ignored for single-node workstations.

TEXT

Docker base image for every node (default: nvidia/cuda:12.8.1-devel-ubuntu24.04). Multi-node workstations install Slurm with apt at startup, so use a Debian-based image.

Mount checkpoint storage on the workstation. See Checkpoints.

TEXT

Path inside the container to save checkpoints.

INTEGER

Checkpoint volume size in GiB.

TEXT

Job ID to load the latest checkpoint from.

TEXT

Name of the remote in .trussrc to use.

TEXT

Name of the team that owns the workstation’s training project. If not specified, falls back to the team configured for the remote in .trussrc.

The --team flag is only available if your organization has teams enabled. Contact us to enable teams, or see Teams for more information.

Stream workstation status and logs after launch.

humanfriendly | W | WARNING | I | INFO | D | DEBUG

default:"humanfriendly"

Customizes logging.

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

Examples

Launch a workstation with default settings:

truss train workstation

Launch a multi-GPU workstation:

truss train workstation --accelerator H200 --gpu-count 4

Launch a workstation with a custom base image:

truss train workstation --image pytorch/pytorch:2.7.0-cuda12.8-cudnn9-runtime

capacity

Manage GPU training capacity for your organization.

view

Show GPU capacity limits and current usage for the organization and teams.

truss train capacity view [OPTIONS]

Options

TEXT

Name of the remote to use

Examples

View capacity for the default remote:

truss train capacity view

Output:

                Training GPU Capacity
╭──────────┬──────────┬───────┬───────────┬──────╮
│ GPU Type │ Baseline │ Limit │ On-Demand │ Spot │
├──────────┼──────────┼───────┼───────────┼──────┤
│ L4       │        4 │     8 │         0 │    0 │
╰──────────┴──────────┴───────┴───────────┴──────╯
            Team Training GPU Capacity
╭─────────┬──────────┬───────┬───────────┬──────╮
│ Team    │ GPU Type │ Limit │ On-Demand │ Spot │
├─────────┼──────────┼───────┼───────────┼──────┤
│ ML-Perf │ L4       │    10 │         0 │    0 │
╰─────────┴──────────┴───────┴───────────┴──────╯

update

Set a team’s GPU training capacity ceiling. Org-admin only.

truss train capacity update [OPTIONS]

Options

TEXT

Name of the remote to use

TEXT

Team to update GPU capacity for.

TEXT

GPU type to update capacity for (e.g. H100).

INTEGER

Max concurrent GPUs of this type the team may use. Org-admin only.

Examples

Set a team’s H100 capacity limit:

truss train capacity update --team ml-research --gpu-type H100 --capacity 32

Ignore files and folders

Create a .truss_ignore file in your project root to exclude files from upload. Uses .gitignore syntax.

.truss_ignore

# Python cache files
__pycache__/
*.pyc
*.pyo
*.pyd

# Type checking
.mypy_cache/

# Testing
.pytest_cache/

# Large data files
data/
*.bin

​init

​Options

​Examples

​push

​Arguments

​Options

​Examples

​logs

​Options

​Examples

​metrics

​Options

​Examples

​view

​Options

​Examples

​stop

​Options

​Examples

​update

​Options

​Examples

​recreate

​Options

​Examples

​download

​Options

​Examples

​deploy_checkpoints

​Options

​Examples

​Output

​get_checkpoint_urls

​Options

​Examples

​checkpoints list

​Options

​Interactive mode

​Examples

​cache summarize

​Arguments

​Options

​Examples

​isession

​Options

​Examples

​update_session

​Arguments

​Options

​Examples

​workstation

​Options

​Examples

​capacity

​view

​Options

​Examples

​update

​Options

​Examples

​Ignore files and folders

init

Options

Examples

push

Arguments

Options

Examples

logs

Options

Examples

metrics

Options

Examples

view

Options

Examples

stop

Options

Examples

update

Options

Examples

recreate

Options

Examples

download

Options

Examples

deploy_checkpoints

Options

Examples

Output

get_checkpoint_urls

Options

Examples

checkpoints list

Options

Interactive mode

Examples

cache summarize

Arguments

Options

Examples

isession

Options

Examples

update_session

Arguments

Options

Examples

workstation

Options

Examples

capacity

view

Options

Examples

update

Options

Examples

Ignore files and folders