> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osmosis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Reference

> Review all Osmosis CLI commands

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:

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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 |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis template list
```

Lists available starter templates.

### template apply

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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    |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis eval submit configs/eval/my-rollout.toml
```

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

### eval list

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

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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](/cli/config-files#env-and-secrets) 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).

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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**.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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`.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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                          |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
# 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`.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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  |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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) |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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.

<Note>
  `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.
</Note>

***

## train

Submit and manage training runs for the current workspace repository.

### train submit

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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                |

<Note>
  Config values come from the local TOML file. Training code comes from the synced workspace repository.
</Note>

### train info

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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`).

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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`).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
{
  "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.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis model info <lora-model>
```

### model deploy

Deploy or reactivate a LoRA model by name.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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.

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis model undeploy <lora-model>
```

<Note>
  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.
</Note>

***

## upgrade

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis upgrade
```

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