Command Reference

Run osmosis -h to see all available commands. Every sub-command supports -h / --help. The global output flags --json and --plain are position-independent — they work before or after the command:

osmosis --json <command>
osmosis <command> --json

Use --json for automation and AI agents. Use --plain for low-noise shell output.

auth

Manage CLI authentication.

Command	Description
`osmosis auth login`	Authenticate via browser OAuth or personal access token
`osmosis auth logout`	Revoke the current session and clear local credentials
`osmosis auth whoami`	Show the authenticated user, token expiration, and linked workspace

osmosis auth login
osmosis auth whoami

When you run osmosis auth whoami from inside a workspace repository, the CLI also resolves the linked Platform workspace. --json reports it as a workspace object (id, name, role); other modes show Workspace and Role rows. Outside a workspace repository, or when offline or logged out, workspace is null and the command still works.

doctor

Inspect and optionally repair the workspace directory scaffold.

osmosis doctor [path] [--fix]

Argument / Option	Type	Default	Description
`path`	`path`	`.`	Path inside the workspace directory
`--fix`	flag	—	Create missing scaffold directories without overwriting existing files

When you are logged in and the workspace directory has a Platform-connected origin remote, doctor also reports the linked workspace (Linked workspace: <name>, or the workspace resource field in --json). The lookup is best-effort — offline or logged out, the field is null and doctor still works.

template

Add starter rollouts from the Osmosis workspace template catalog.

template list

osmosis template list

Lists available starter templates.

template apply

osmosis template apply <name> [--force]

Argument / Option	Type	Description
`name`	`str` (required)	Template name from `osmosis template list`
`-f`, `--force`	flag	Replace the template-owned rollout directory and config files

rollout

Create local rollout scaffolds and list synced rollouts.

rollout init

osmosis rollout init <name> [--force]

Creates:

rollouts/<name>/main.py
rollouts/<name>/pyproject.toml
rollouts/<name>/README.md
configs/eval/<name>.toml
configs/training/<name>.toml

Argument / Option	Type	Description
`name`	`str` (required)	Lowercase rollout name using letters, digits, and hyphens
`-f`, `--force`	flag	Replace existing scaffold paths for this rollout

rollout list

osmosis rollout list [--limit N] [--all]

Option	Type	Default	Description
`--limit`	`int`	`50`	Maximum number of rollouts to show
`--all`	flag	—	Show all rollouts

eval

Submit and manage evaluation runs, and run LLM-as-judge rubric scoring locally.

eval submit

Submit an evaluation run from a TOML config under configs/eval/. The platform clones the workspace repository identified by the origin remote and runs the rollout server-side, so push your commits before submitting.

osmosis eval submit <config_path> [--yes]

Argument / Option	Type	Description
`config_path`	`path` (required)	Eval TOML under `configs/eval/`
`-y`, `--yes`	flag	Skip the confirmation prompt

osmosis eval submit configs/eval/my-rollout.toml

Config values come from the local TOML file. Rollout code comes from the synced workspace repository (or the pinned [experiment].commit_sha).

eval list

List evaluation runs for the current workspace repository, including each run’s status, average reward, and progress.

osmosis eval list [--limit N] [--all]

Option	Type	Default	Description
`--limit`	`int`	`50`	Maximum number of evaluation runs to show
`--all`	flag	—	Show all evaluation runs

eval info

Show details, results, and metrics for an evaluation run.

osmosis eval info <name_or_id> [--output PATH]

Argument / Option	Type	Description
`name_or_id`	`str` (required)	Evaluation run name or ID
`-o`, `--output`	`path`	Where to write the metrics JSON file

The sidebar shows status, progress (rows completed and percent), and duration. Below the sidebar, the output includes:

Summary — pass rate, tokens used, reward stats (including mean), and per-status row counts.
Configuration — entrypoint, commit SHA, dataset stats, pass thresholds, pass@k, token limits, timeouts, [env] keys, and resolved secret scopes.
Results — per-row reward, pass/fail, and the most recent platform logs.

For completed runs, eval info also fetches metrics (duration, pass rate, tokens used, reward statistics, and pass@k) from the platform and exports them as JSON:

In rich mode, the CLI saves metrics under .osmosis/metrics/ by default when metrics are available.
In JSON or plain mode, pass -o / --output to write the metrics file.
A trailing slash or existing directory uses the default filename. The CLI replaces non-.json extensions and creates parent directories automatically.
If metrics are not yet available (for example, the run is still pending), the CLI prints a notice instead of writing a file.

osmosis eval info my-eval-run
osmosis --json eval info my-eval-run -o ./eval-metrics.json

eval stop

Stop a pending or running evaluation run.

osmosis eval stop <name_or_id> [--yes]

Argument / Option	Type	Description
`name_or_id`	`str` (required)	Evaluation run name or ID
`-y`, `--yes`	flag	Skip the confirmation prompt

eval logs

Show the most recent lifecycle logs for an evaluation run, oldest first. Use this to diagnose failed runs.

osmosis eval logs <name_or_id> [--limit N] [--cursor CURSOR]

Argument / Option	Type	Default	Description
`name_or_id`	`str` (required)	—	Evaluation run name or ID
`--limit`	`int`	`50`	Entries per page (1–200)
`--cursor`	`str`	—	Cursor from a previous page’s `next_cursor`

When older entries exist, --json output includes a non-null next_cursor. Pass it back with --cursor to page further back in time.

eval rubric

Run LLM-as-judge evaluation locally over a JSONL conversation file. This sub-command does not require a workspace directory or platform authentication and does not run a rollout.

osmosis eval rubric -d <data.jsonl> -r <rubric> --model <model>

Option	Type	Default	Description
`-d`, `--data`	`str` (required)	—	Path to JSONL conversations
`-r`, `--rubric`	`str` (required)	—	Rubric text or `@file.txt`
`--model`	`str` (required)	—	Judge model in LiteLLM format
`-n`, `--number`	`int`	`1`	Number of evaluation runs per record
`-o`, `--output`	`str`	—	Path for JSON output
`--api-key`	`str`	—	API key for the judge model
`--timeout`	`float`	—	Request timeout in seconds
`--score-min`	`float`	`0.0`	Minimum score
`--score-max`	`float`	`1.0`	Maximum score

secret

Manage environment_secret records referenced by the [secrets].required list in train and eval configs. The platform never returns secret values — these commands show or accept names and metadata only. Values are read from a hidden interactive prompt or a named environment variable, never as a plaintext command-line argument. Each secret has a scope:

Workspace secrets are shared across the workspace. Creating, updating, or deleting them requires an admin or owner role.
Personal secrets are private to you. When a workspace and a personal secret share a name, your personal value wins at run time. Use personal secrets for overrides, such as swapping in your own provider API key without affecting teammates.

Secret names must match ^[A-Z][A-Z0-9_]*$ (SCREAMING_SNAKE_CASE).

secret list

List secrets visible to you in the current workspace (names and metadata only — never values).

osmosis secret list [--scope all|workspace|personal] [--limit N] [--all]

Option	Type	Default	Description
`--scope`	`str`	`all`	Filter by scope: `all`, `workspace`, or `personal`
`--limit`	`int`	`50`	Maximum number of secrets to show
`--all`	flag	—	Show all secrets

The output includes a Scope column labeled Workspace or Personal.

osmosis secret list
osmosis secret list --scope personal

secret set

Create or update (upsert) a secret. The CLI reads the value from the env var named by --env VARNAME; without that flag, you type the value at a hidden interactive prompt. In --json or --plain (non-interactive) modes, you must pass --env.

osmosis secret set <name> [--scope workspace|personal] [--env VARNAME]

Argument / Option	Type	Default	Description
`name`	`str` (required)	—	Secret name in `^[A-Z][A-Z0-9_]*$`
`--scope`	`str`	`personal`	`personal` (private to you) or `workspace` (shared with the workspace)
`--env`	`str`	—	Read the value from this environment variable

# Create or update your personal secret (default scope):
osmosis secret set OPENAI_API_KEY

# Read the value from an env var (recommended for scripts and CI):
OPENAI_API_KEY=sk-... osmosis secret set OPENAI_API_KEY --env OPENAI_API_KEY

# Workspace-shared secret (requires admin or owner role):
OPENAI_API_KEY=sk-... osmosis secret set OPENAI_API_KEY --scope workspace --env OPENAI_API_KEY

secret delete

Delete a secret within the given scope. The CLI prompts you to confirm unless you pass --yes.

osmosis secret delete <name> [--scope workspace|personal] [--yes]

Argument / Option	Type	Default	Description
`name`	`str` (required)	—	Secret name to delete
`--scope`	`str`	`personal`	Scope of the secret to delete
`-y`, `--yes`	flag	—	Skip the confirmation prompt

osmosis secret delete OPENAI_API_KEY --yes
osmosis secret delete OPENAI_API_KEY --scope workspace --yes

dataset

Manage platform datasets for the current workspace repository.

Command	Description
`osmosis dataset upload <file> [--overwrite] [--yes]`	Upload a CSV, JSONL, or Parquet dataset
`osmosis dataset download <name> [-o PATH] [--overwrite]`	Download a dataset file
`osmosis dataset list [--limit N] [--all]`	List datasets
`osmosis dataset info <name>`	Show dataset details and processing status
`osmosis dataset preview <name> [--rows N]`	Preview uploaded dataset rows
`osmosis dataset validate <file>`	Validate a dataset locally
`osmosis dataset logs <name> [--limit N] [--cursor CURSOR]`	Show lifecycle logs for a dataset (oldest first)

osmosis dataset upload data/train.jsonl
osmosis dataset info train
osmosis dataset preview train --rows 5

Dataset names are derived from the file name without its extension. If a dataset with that name already exists, the upload fails — pass --overwrite to replace it (the old record is soft-deleted). Use osmosis dataset logs <name> to diagnose failed uploads. --limit accepts 1–200 entries (default: 50). When older entries exist, the --json output includes a non-null next_cursor; pass it back with --cursor to page further back in time.

osmosis dataset upload requires --yes (-y) in non-interactive modes (--json, --plain, or when stdin is piped). Running without it raises INTERACTIVE_REQUIRED, even with --overwrite. Add --yes to CI jobs and scripted uploads to skip the confirmation prompt.

train

Submit and manage training runs for the current workspace repository.

train submit

osmosis train submit <config_path> [--yes]

Argument / Option	Type	Description
`config_path`	`path` (required)	Training TOML under `configs/training/`
`-y`, `--yes`	flag	Skip confirmation prompt

Config values come from the local TOML file. Training code comes from the synced workspace repository.

train info

osmosis train info <name> [--output PATH]

Shows run details, checkpoints, and metrics. The summary panel includes progress (current_step / total_steps with percent complete) and the latest reward while the run is in flight. In rich mode, metrics are saved under .osmosis/metrics/ by default.

train logs

Show the most recent lifecycle logs for a training run, oldest first. Use this to diagnose failed or crashed runs.

osmosis train logs <name> [--limit N] [--cursor CURSOR]

Argument / Option	Type	Default	Description
`name`	`str` (required)	—	Training run name
`--limit`	`int`	`50`	Entries per page (1–200)
`--cursor`	`str`	—	Cursor from a previous page’s `next_cursor`

When older entries exist, --json output includes a non-null next_cursor. Pass it back with --cursor to page further back in time.

Other train commands

osmosis train list [--limit N] [--all]
osmosis train stop <name> [--yes]

train list shows status, current step / total steps, and the latest reward for each run.

model

Manage base (foundation) models and LoRA models produced by training runs. Deploying a LoRA model exposes it for inference.

model list

List base models and LoRA models for the current workspace as two independently paginated sections (base first, then LoRA). The base table shows Name, Created, and Created By. The LoRA table shows Name, Base Model, Training Run, Checkpoint Step, Training Reward, and Created. When deployment info is available, the LoRA table also shows Deployment Status and a deployment-quota summary below it (for example, 2 of 5 inference deployments used).

osmosis model list [--type all|base|lora] [--limit N] [--all]

Option	Type	Default	Description
`--type`	`str`	`all`	Filter to a single list: `all`, `base`, or `lora`
`--limit`	`int`	`50`	Maximum number of models to show per type
`--all`	flag	—	Show all models of each type

--limit and --all apply to each list independently, and each list carries its own pagination cursor (next_offset).

osmosis model list
osmosis model list --type lora
osmosis model list --type base --limit 50
osmosis --json model list

--json output keys each list separately, so the structure itself identifies which list is which:

{
  "base_models": { "items": [...], "next_offset": null },
  "lora_models": { "items": [...], "next_offset": null },
  "active_deployments": 2,
  "max_active_deployments": 5
}

When deployment info is available, the active_deployments / max_active_deployments quota keys appear for --type all and --type lora, but not for --type base.

model info

Show details for a single LoRA model: base model, training run, checkpoint step, training reward, Hugging Face export status, and deployment status when deployment info is available.

osmosis model info <lora-model>

model deploy

Deploy or reactivate a LoRA model by name.

osmosis model deploy <lora-model>

model undeploy

Transition a LoRA model’s deployment to inactive (idempotent). The LoRA model remains in the training run history.

osmosis model undeploy <lora-model>

The standalone osmosis deployment, osmosis deploy, and osmosis undeploy commands have been removed. Use osmosis model deploy <lora-model> and osmosis model undeploy <lora-model> instead.

upgrade

Self-upgrade the CLI to the latest version published on PyPI.

osmosis upgrade

The CLI auto-detects your install method (pip, pipx, or uv tool) and runs the appropriate upgrade command.

​auth

​doctor

​template

​template list

​template apply

​rollout

​rollout init

​rollout list

​eval

​eval submit

​eval list

​eval info

​eval stop

​eval logs

​eval rubric

​secret

​secret list

​secret set

​secret delete

​dataset

​train

​train submit

​train info

​train logs

​Other train commands

​model

​model list

​model info

​model deploy

​model undeploy

​upgrade

auth

doctor

template

template list

template apply

rollout

rollout init

rollout list

eval

eval submit

eval list

eval info

eval stop

eval logs

eval rubric

secret

secret list

secret set

secret delete

dataset

train

train submit

train info

train logs

Other train commands

model

model list

model info

model deploy

model undeploy

upgrade