baseten train init and baseten train push, run it as a job, and deploy the checkpoints the job syncs. Projects group jobs and share a cache.
init
Options
Directory to create. Defaults to ./truss-train-init for an empty project, or the current directory when examples are named.
Name of a published training example to download instead of the empty template. Repeatable.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.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.Examples
Scaffold an empty training projectOutput
Text mode (--output text): A line per directory created, naming where it was written. With --list-examples, the available example names, one per line.
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.
push
--job-id id --tail’.
Options
Accelerator type and count, for example ‘H200:8’. Overrides the config. Supported hardware is documented at https://docs.baseten.co/training/concepts/basics.
How long an interactive session stays up, as a duration (e.g. ‘90m’, ‘2h’). Rounded down to whole minutes; must be at least 1m.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Run on interruptible spot capacity, overriding the config. Checkpointing your own progress is up to you.
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.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.
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.Examples
Run a training job from a config fileOutput
Text mode (--output text): A confirmation that the job was created, with its ID, the commands to follow it, and a link to it in the Baseten UI.
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.
job
Submit training jobs, then read their logs and metrics, change their priority, and stop or recreate them.list
--project to narrow to one project, or --status to narrow to particular job states.
Options
Sort order by creation time: ‘desc’ (newest first) or ‘asc’ (oldest first).One of:
asc, descUse a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Only list jobs in these states: pending, created, deploying, deploy-failed, running, completed, failed, stopped, preempted. Repeatable.
Examples
List every training job you can seeFilter output with --jq
Print just the job IDs
Output
Text mode (--output text): Table with columns: ID, PROJECT, NAME, STATUS, INSTANCE TYPE, NODES, CREATED. When no jobs match, prints “No training jobs found.” to stderr.
JSON mode (--output json): payload type managementapi.SearchTrainingJobsResponse.
describe
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Describe a jobFilter output with --jq
Print the job’s current status
Output
Text mode (--output text): A field-per-line summary of the job and its project.
JSON mode (--output json): payload type managementapi.GetTrainingJobResponse.
logs
--tail, returns the logs in a time window; with --tail, streams new logs until the job stops producing them or you interrupt with Ctrl-C.
Options
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.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.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.
Stream new logs as they arrive until the job 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.Examples
Fetch the last 30 minutes of logsFilter output with --jq
Print just the log messages
Output
Text mode (--output text): One log line per row, timestamped. With --output jsonl, one JSON log record per line.
JSON mode (--output json): payload type managementapi.GetLogsResponse.
metrics
--start and --end, or --since, to select the window the samples come from.
Options
End of the sample window. Accepts ISO 8601; values without a timezone designator are interpreted in the local timezone. Default is now.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Shortcut for sampling from a relative time ago until now. Accepts a duration (e.g. ‘30m’, ‘1h30m’) or ‘
Nd’ (e.g. ‘3d’). Mutually exclusive with --start and --end.Start of the sample window. Accepts ISO 8601; values without a timezone designator are interpreted in the local timezone.
Examples
Report a job’s latest metricsFilter output with --jq
Print the GPU utilization series
Output
Text mode (--output text): Table with columns: METRIC, NODE, VALUE, MEASURED.
JSON mode (--output json): payload type managementapi.GetTrainingJobMetricsResponse.
stop
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Stop a job, confirming interactivelyFilter output with --jq
Print the stopped job’s status
Output
Text mode (--output text): On success, prints the stopped job’s ID to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.StopTrainingJobResponse.
recreate
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Rerun a job’s configurationFilter output with --jq
Print just the new job’s ID
Output
Text mode (--output text): On success, prints the new job’s ID to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.RecreateTrainingJobResponse.
update
standard capacity to spot to admit it sooner.
Only jobs in the PENDING state can be updated.
Options
New capacity guarantee. ‘standard’ runs on capacity that is not preempted; ‘spot’ runs on interruptible capacity that may be preempted, and checkpointing your own progress is up to you.One of:
standard, spotUse a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Raise a queued job’s priorityFilter output with --jq
Print the job’s new priority
Output
Text mode (--output text): On success, prints the job’s ID and what changed to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.UpdateTrainingJobResponse.
download
--out-file or --out-dir is required. --out-file writes the raw tar bytes; --out-dir extracts the tar into the directory. Use --overwrite to replace an existing file or write into a non-empty directory.
This is the job’s input code, not its checkpoints; use ‘baseten train checkpoint files’ for those.
Options
Extract the artifact tar into this directory.Mutually exclusive with other flags in group
download-out.Save the artifact as an uncompressed tar file at this path.Mutually exclusive with other flags in group
download-out.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Extract a job’s code into a directoryFilter output with --jq
Print just the destination path
Output
Text mode (--output text): Writes the artifact to disk; prints progress and the final destination path to stderr; no stdout output.
JSON mode (--output json): payload type cmd.TrainJobDownloadResult.
On success, stdout is a JSON object naming the job, with either out_file or out_dir set to the path written.
job session
A running job can hold an interactive session on each replica. Describe those sessions.describe
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Show a job’s interactive sessionsFilter output with --jq
Print the first replica’s auth URL
Output
Text mode (--output text): Table with columns: REPLICA, SESSION, AUTH URL, EXPIRES. When no session is live, prints “No interactive sessions found.” to stderr.
JSON mode (--output json): payload type managementapi.GetAuthCodesResponse.
capacity
Capacity is the number of GPUs of each type a team may use concurrently. Read the limits and raise them per team.describe
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Describe training GPU capacityFilter output with --jq
Print the organization’s H100 limit
Output
Text mode (--output text): An organization table with columns: GPU TYPE, IN USE, LIMIT, BASELINE, then a per-team table with a leading TEAM column when teams have limits set.
JSON mode (--output json): payload type managementapi.GetTrainingGpuCapacityResponse.
update
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Raise a team’s H100 limitFilter output with --jq
Print the applied limit
Output
Text mode (--output text): On success, prints the team, GPU type, and new limit to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.PatchTeamTrainingGpuCapacityResponse.
checkpoint
Jobs that enable checkpointing sync their checkpoints. List them, download their files, and deploy LoRA checkpoints as a model served by vLLM.list
Options
Sort order by creation time: ‘desc’ (newest first) or ‘asc’ (oldest first).One of:
asc, descUse a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List a job’s checkpointsFilter output with --jq
Print just the checkpoint IDs
Output
Text mode (--output text): Table with columns: ID, TYPE, BASE MODEL, SIZE, SYNC, CREATED. When the job has no checkpoints, prints “No checkpoints found.” to stderr.
JSON mode (--output json): payload type managementapi.GetTrainingJobCheckpointsResponse.
files
--output jsonl over --output json.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List every checkpoint file of a jobFilter output with --jq
Print just the download URLs
Output
Text mode (--output text): Table with columns: NODE, NAME, SIZE, MODIFIED, URL. When there are no files, prints “No checkpoint files found.” to stderr.
JSON mode (--output json): payload type managementapi.CheckpointFile.
deploy
--config, the checkpoints and the model that serves them are chosen interactively. Pass --config for a repeatable deploy: it is a Python file defining a DeployCheckpointsConfig, so it is executed rather than read.
The generated model config is written to disk either way, so a deploy can be re-run or edited by hand afterward.
Options
Python file defining a DeployCheckpointsConfig: which checkpoints deploy and the model that serves them. The type is documented at https://docs.baseten.co/reference/sdk/training#deploycheckpointsconfig.
Directory the generated model config is written to. Defaults to a directory under ./truss_configs.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.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.
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.Examples
Deploy a job’s checkpoints, choosing them interactivelyOutput
Text mode (--output text): The new model and deployment IDs with links to the deployment’s logs, the path the model config was written to, and an example request naming the deployed checkpoints. With --dry-run, only the config path.
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.
project
Projects group training jobs and share a cache.list
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List your training projectsFilter output with --jq
Print just the project names
Output
Text mode (--output text): Table with columns: ID, NAME, TEAM, LATEST JOB, LATEST STATUS, CREATED. When there are no projects, prints “No training projects found.” to stderr.
JSON mode (--output json): payload type managementapi.ListTrainingProjectsResponse.
project cache
describe
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Sort the listing by ‘size’ (largest first) or ‘path’ (alphabetical).One of:
size, pathExamples
Describe a project’s cacheFilter output with --jq
Print the cached file paths
Output
Text mode (--output text): A total size line, then a table with columns: PATH, TYPE, SIZE, PERMISSIONS, MODIFIED. When the cache is empty, prints “Cache is empty.” to stderr.
JSON mode (--output json): payload type managementapi.GetCacheSummaryResponse.
workstation
A workstation is a training job that holds GPUs for an interactive SSH session instead of running a script.create
--node-count for a multi-node workstation, where each node has eight GPUs and SLURM is set up across them. Connect once the job is running.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.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.
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.Examples
Create a single-GPU workstationOutput
Text mode (--output text): A confirmation that the workstation was created, with the ssh host of each node and the commands to view its logs or stop it.
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.