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

# baseten train

> Manage training projects and jobs

## init

```sh theme={"system"}
baseten train init [OPTIONS]
```

Create a training project directory, either empty from the built-in template or from one of the published training examples.

This command needs no credentials: it only writes files, and the examples are downloaded from a public repository.

### Options

<ParamField body="--dir" type="TEXT">
  Directory to create. Defaults to ./truss-train-init for an empty project, or the current directory when examples are named.
</ParamField>

<ParamField body="--example" type="TEXT (repeatable)">
  Name of a published training example to download instead of the empty template. Repeatable.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--list-examples" type="BOOL">
  List the available example names and exit.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--truss-executable" type="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.
</ParamField>

<ParamField body="--truss-version" type="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.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Scaffold an empty training project

```sh theme={"system"}
baseten train init --dir ./my-training
```

List the available examples

```sh theme={"system"}
baseten train init --list-examples
```

Download two examples into the current directory

```sh theme={"system"}
baseten train init --example sft-lora --example grpo
```

### Output

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

```sh theme={"system"}
baseten train push [OPTIONS]
```

Create and start a training job, uploading the config file's directory as the job's code.

The config is a Python file that defines the training project and its job, so it is executed rather than read. The flags below override what it declares.

Returns once the job is created. Follow it with 'baseten train job logs --job-id `id` --tail'.

### Options

<ParamField body="--accelerator" type="TEXT">
  Accelerator type and count, for example 'H200:8'. Overrides the config.
</ParamField>

<ParamField body="--config" type="TEXT" required>
  Python file defining the training project and its job.
</ParamField>

<ParamField body="--entrypoint" type="TEXT">
  Command the job runs. Overrides the config.
</ParamField>

<ParamField body="--interactive" type="TEXT">
  Start an interactive session on this trigger.

  One of: `on-startup`, `on-failure`, `on-demand`
</ParamField>

<ParamField body="--interactive-timeout" type="TEXT">
  How long an interactive session stays up, as a duration (e.g. '90m', '2h'). Rounded down to whole minutes; must be at least 1m.
</ParamField>

<ParamField body="--job-name" type="TEXT">
  Name for the training job. Defaults to a generated name.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--node-count" type="INTEGER">
  Number of compute nodes. Overrides the config.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--priority" type="INTEGER">
  Queue priority. Higher values are dequeued first.
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--spot" type="BOOL">
  Run on interruptible spot capacity, overriding the config. Checkpointing your own progress is up to you.
</ParamField>

<ParamField body="--team" type="TEXT">
  Team name or ID that owns the training project.
</ParamField>

<ParamField body="--truss-executable" type="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.
</ParamField>

<ParamField body="--truss-no-forward-auth" type="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.
</ParamField>

<ParamField body="--truss-version" type="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.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Run a training job from a config file

```sh theme={"system"}
baseten train push --config ./train.py
```

Run a named job on eight H200s over spot capacity

```sh theme={"system"}
baseten train push --config ./train.py --job-name sweep-3 --accelerator H200:8 --spot
```

Run a job that opens an interactive session if it fails

```sh theme={"system"}
baseten train push --config ./train.py --interactive on-failure --interactive-timeout 2h
```

### Output

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