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

# 命令参考

> 查看所有 Osmosis CLI 命令

运行 `osmosis -h` 查看所有可用命令。每个 sub-command 都支持 `-h` / `--help`。

全局输出 flags `--json` 和 `--plain` 位置无关 —— 在 command 之前或之后均可使用：

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

使用 `--json` 便于自动化和 AI agents。使用 `--plain` 获得低噪声 shell 输出。

***

## auth

管理 CLI 认证。

| Command               | Description                            |
| --------------------- | -------------------------------------- |
| `osmosis auth login`  | 通过浏览器 OAuth 或 personal access token 认证 |
| `osmosis auth logout` | 撤销当前 session 并清除本地凭证                   |
| `osmosis auth whoami` | 显示已认证用户、token 过期时间和已链接的 workspace      |

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

在 workspace repository 内运行 `osmosis auth whoami` 时，CLI 也会解析已链接的 Platform workspace，并在 `--json` 中作为 `workspace` 对象（`id`、`name`、`role`）返回，或在普通输出中以 `Workspace` 和 `Role` 行显示。在 workspace repository 之外，或离线、未登录时，`workspace` 为 `null`，命令仍可正常工作。

***

## doctor

检查并可选修复 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` | `.`     | workspace directory 内的路径   |
| `--fix`           | flag   | —       | 创建缺失的 scaffold 目录，且不覆盖已有文件 |

当您已登录且 workspace directory 的 `origin` remote 连接到 Platform 时，`doctor` 也会报告已链接的 workspace（`Linked workspace: <name>`，在 `--json` 中作为 `workspace` resource 字段）。该查询为尽力而为 —— 离线或未登录时该字段为 `null`，`doctor` 仍可正常工作。

***

## template

从 Osmosis workspace template catalog 添加 starter rollouts。

### template list

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

列出可用 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) | 来自 `osmosis template list` 的 template name       |
| `-f`, `--force`   | flag             | 替换 template 拥有的 rollout directory 和 config files |

***

## rollout

创建本地 rollout scaffolds，并列出已同步 rollouts。

### rollout init

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis rollout init <name> [--force]
```

会创建：

* `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) | 使用小写字母、数字和 hyphens 的 rollout name |
| `-f`, `--force`   | flag             | 替换该 rollout 的已有 scaffold paths    |

### 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`    | 最多显示的 rollouts 数量 |
| `--all`   | flag  | —       | 显示所有 rollouts     |

***

## eval

提交并管理 evaluation runs，并在本地运行 LLM-as-judge rubric 评分。

### eval submit

从 `configs/eval/` 下的 TOML config 提交一次 evaluation run。平台会克隆由 `origin` remote 标识的 workspace repository，并在服务端运行 rollout，因此请在提交前 push commits。

```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) | `configs/eval/` 下的 eval TOML |
| `-y`, `--yes`     | flag              | 跳过确认提示                       |

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

<Note>
  Config 值来自本地 TOML 文件。Rollout 代码来自已同步的 workspace repository（或固定的 `[experiment].commit_sha`）。
</Note>

### eval list

列出当前 workspace repository 的 evaluation runs，包含每次 run 的 status、平均 reward 和进度。

```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`    | 最多显示的 evaluation runs 数量 |
| `--all`   | flag  | —       | 显示所有 evaluation runs     |

### eval info

显示某次 evaluation run 的详细信息、结果与 metrics。

```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 名称或 ID |
| `-o`, `--output`  | `path`           | metrics JSON 文件的写入路径  |

侧栏显示 status、进度（已完成行数和百分比）和耗时。下方输出包括：

* **Summary** — pass rate、tokens 使用量、reward 统计（含 mean），以及按 status 分组的行数统计。
* **Configuration** — entrypoint、commit SHA、dataset 统计、pass 阈值、pass\@k、token 限额、超时、`[env]` 键和已解析的 secret scope。
* **Results** — 每行的 reward、pass/fail 结果以及最近的平台日志。

对于已完成的 run，`eval info` 还会从平台拉取 metrics（耗时、pass rate、tokens 使用量、reward 统计、pass\@k），并导出为 JSON：

* 在 rich 模式下，若 metrics 可用，CLI 会默认将其保存到 `.osmosis/metrics/`。
* 在 JSON 或 plain 模式下，使用 `-o` / `--output` 指定 metrics 文件的写入路径。
* 路径以斜杠结尾或为已有目录时使用默认文件名。CLI 会替换非 `.json` 的后缀，并自动创建上级目录。
* 若 metrics 尚不可用（例如 run 仍处于 pending 状态），CLI 会打印提示，而不会写入文件。

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

停止一次 pending 或 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 名称或 ID |
| `-y`, `--yes`     | flag             | 跳过确认提示                |

### eval logs

按时间顺序（从最早开始）显示 evaluation run 的最近生命周期日志。用于诊断失败的运行。

```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 名称或 ID   |
| `--limit`         | `int`            | `50`    | 每页条数（1–200）             |
| `--cursor`        | `str`            | —       | 上一页 `next_cursor` 返回的游标 |

当存在更早的条目时，`--json` 输出会包含非 `null` 的 `next_cursor`。将其传给 `--cursor` 即可继续向前翻页。

### eval rubric

对 JSONL conversation 文件在本地运行 LLM-as-judge evaluation。该子命令不需要 workspace directory 或平台认证，也不会运行 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) | —       | JSONL conversations 路径         |
| `-r`, `--rubric` | `str` (required) | —       | rubric 文本或 `@file.txt`         |
| `--model`        | `str` (required) | —       | LiteLLM 格式的 judge model        |
| `-n`, `--number` | `int`            | `1`     | 每条 record 的 evaluation runs 数量 |
| `-o`, `--output` | `str`            | —       | JSON output 路径                 |
| `--api-key`      | `str`            | —       | judge model 的 API key          |
| `--timeout`      | `float`          | —       | request timeout，单位秒            |
| `--score-min`    | `float`          | `0.0`   | 最小分数                           |
| `--score-max`    | `float`          | `1.0`   | 最大分数                           |

***

## secret

管理被 train 和 eval config 中 [`[secrets].required` 列表](/zh/cli/config-files#env-and-secrets) 引用的 `environment_secret` 记录。平台从不返回 secret 值——这些命令只显示或接受 names 和 metadata。值通过隐藏的交互式 prompt 或具名环境变量读取，绝不通过明文命令行参数传入。

每个 secret 都有 **scope**：

* **Workspace** secrets 在 workspace 内共享，创建、更新或删除需要 admin 或 owner 角色。
* **Personal** secrets 是您个人私有的。当 workspace 与 personal secret 同名时，运行时使用您的 personal 值。把 personal secrets 用于覆盖，例如替换自己的 provider API key 而不影响队友。

Secret 名称必须匹配 `^[A-Z][A-Z0-9_]*$`（SCREAMING\_SNAKE\_CASE）。

### secret list

列出当前 workspace 中您可见的 secrets（只显示 names 和 metadata，从不显示值）。

```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`   | 按 scope 过滤：`all`、`workspace` 或 `personal` |
| `--limit` | `int` | `50`    | 最多显示的 secrets 数                           |
| `--all`   | flag  | —       | 显示所有 secrets                              |

输出包含一列 Scope，标记为 **Workspace** 或 **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

创建或更新（upsert）一个 secret。CLI 从 `--env VARNAME` 指定的环境变量读取值；若未指定该 flag，您在隐藏的交互式 prompt 中输入。在 `--json` 或 `--plain`（非交互）模式下，您必须传入 `--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） | —          | 匹配 `^[A-Z][A-Z0-9_]*$` 的 secret 名称             |
| `--scope`         | `str`           | `personal` | `personal`（您本人私有）或 `workspace`（与 workspace 共享） |
| `--env`           | `str`           | —          | 从该环境变量读取值                                      |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
# 创建或更新您的 personal secret（默认 scope）：
osmosis secret set OPENAI_API_KEY

# 从 env var 读取值（推荐用于脚本和 CI）：
OPENAI_API_KEY=sk-... osmosis secret set OPENAI_API_KEY --env OPENAI_API_KEY

# Workspace 共享 secret（需要 admin 或 owner 角色）：
OPENAI_API_KEY=sk-... osmosis secret set OPENAI_API_KEY --scope workspace --env OPENAI_API_KEY
```

### secret delete

在指定 scope 中删除一个 secret。除非您传入 `--yes`，CLI 会提示确认。

```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 名称       |
| `--scope`         | `str`           | `personal` | 要删除 secret 所在的 scope |
| `-y`, `--yes`     | flag            | —          | 跳过确认提示               |

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

管理当前 workspace repository 的平台数据集。

| Command                                                     | Description                |
| ----------------------------------------------------------- | -------------------------- |
| `osmosis dataset upload <file> [--overwrite] [--yes]`       | 上传 CSV、JSONL 或 Parquet 数据集 |
| `osmosis dataset download <name> [-o PATH] [--overwrite]`   | 下载数据集文件                    |
| `osmosis dataset list [--limit N] [--all]`                  | 列出数据集                      |
| `osmosis dataset info <name>`                               | 显示数据集详情和处理状态               |
| `osmosis dataset preview <name> [--rows N]`                 | 预览已上传数据集行                  |
| `osmosis dataset validate <file>`                           | 本地验证数据集                    |
| `osmosis dataset logs <name> [--limit N] [--cursor CURSOR]` | 查看数据集的生命周期日志（按时间顺序）        |

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

数据集名称根据文件名（去掉扩展名）生成。如果同名数据集已存在，上传会失败——使用 `--overwrite` 替换它（旧记录会被软删除）。

使用 `osmosis dataset logs <name>` 诊断失败的上传。`--limit` 接受 1–200 条（默认：50）。当存在更早的条目时，`--json` 输出会包含非 `null` 的 `next_cursor`；将其传给 `--cursor` 可继续向前翻页。

<Note>
  `osmosis dataset upload` 在非交互模式下（`--json`、`--plain` 或通过管道传入 stdin）必须显式传入 `--yes`（`-y`）。即使带上 `--overwrite`，缺少 `--yes` 也会抛出 `INTERACTIVE_REQUIRED`。在 CI 任务和脚本化上传中加上 `--yes` 即可跳过确认提示。
</Note>

***

## train

提交并管理当前 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) | `configs/training/` 下的 training TOML |
| `-y`, `--yes`     | flag              | 跳过确认提示                               |

<Note>
  Config 值来自本地 TOML 文件。训练代码来自已同步的 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]
```

显示训练任务详情、checkpoints 和 metrics。运行过程中，summary 面板会显示进度（`current_step` / `total_steps` 及完成百分比）和最新的 reward。在 rich mode 下，metrics 默认保存到 `.osmosis/metrics/`。

### train logs

按时间顺序（从最早开始）显示 training run 的最近生命周期日志。用于诊断失败或崩溃的运行。

```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 名称         |
| `--limit`         | `int`            | `50`    | 每页条数（1–200）             |
| `--cursor`        | `str`            | —       | 上一页 `next_cursor` 返回的游标 |

当存在更早的条目时，`--json` 输出会包含非 `null` 的 `next_cursor`。将其传给 `--cursor` 即可继续向前翻页。

### 其他 train 命令

```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` 会显示每个 run 的 status、当前 step / 总 step 以及最新的 reward。

***

## model

管理 base（基础）models 和由 training runs 产生的 LoRA models。部署 LoRA model 即可将其用于 inference。

### model list

以两个独立分页的部分列出当前 workspace 的 base models 和 LoRA models（先 base，再 LoRA）。base 表显示 Name、Created、Created By。LoRA 表显示 Name、Base Model、Training Run、Checkpoint Step、Training Reward、Created。当 deployment info 可用时，LoRA 表还会显示 Deployment Status，并在下方显示部署配额汇总（例如 `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`   | 仅显示某一类列表：`all`、`base` 或 `lora` |
| `--limit` | `int` | `50`    | 每种类型最多显示的 model 数              |
| `--all`   | flag  | —       | 显示每种类型的所有 models               |

`--limit` 和 `--all` 对每个列表独立生效，每个列表也都各自携带分页游标（`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` 输出对两个列表分别使用不同的 key，结构本身即可表明各列表的归属：

```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
}
```

当 deployment info 可用时，`active_deployments` / `max_active_deployments` 配额字段仅在 `--type all` 和 `--type lora` 中出现，`--type base` 不包含。

### model info

显示单个 LoRA model 的详情：base model、training run、checkpoint step、training reward、Hugging Face 导出状态，以及 deployment info 可用时的部署状态。

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

### model deploy

按名称部署或重新激活 LoRA model。

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

### model undeploy

将 LoRA model 的部署切换为 inactive（幂等操作）。该 LoRA model 仍保留在 training run 历史中。

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

<Note>
  独立的 `osmosis deployment`、`osmosis deploy` 和 `osmosis undeploy` 命令已移除。请改用 `osmosis model deploy <lora-model>` 和 `osmosis model undeploy <lora-model>`。
</Note>

***

## upgrade

将 CLI 自升级到 PyPI 上发布的最新版本。

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

CLI 会自动检测您的安装方式（`pip`、`pipx` 或 `uv tool`），并运行相应升级命令。