命令参考 - Osmosis

运行 osmosis -h 查看所有可用命令。每个 sub-command 都支持 -h / --help。全局输出 flags --json 和 --plain 位置无关 —— 在 command 之前或之后均可使用：

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

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。

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

osmosis template list

列出可用 starter templates。

template apply

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

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

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。

osmosis eval submit <config_path> [--yes]

Argument / Option	Type	Description
`config_path`	`path` (required)	`configs/eval/` 下的 eval TOML
`-y`, `--yes`	flag	跳过确认提示

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

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

eval list

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

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

Option	Type	Default	Description
`--limit`	`int`	`50`	最多显示的 evaluation runs 数量
`--all`	flag	—	显示所有 evaluation runs

eval info

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

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 会打印提示，而不会写入文件。

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

eval stop

停止一次 pending 或 running 的 evaluation run。

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 的最近生命周期日志。用于诊断失败的运行。

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。

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 列表引用的 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，从不显示值）。

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。

osmosis secret list
osmosis secret list --scope personal

secret set

创建或更新（upsert）一个 secret。CLI 从 --env VARNAME 指定的环境变量读取值；若未指定该 flag，您在隐藏的交互式 prompt 中输入。在 --json 或 --plain（非交互）模式下，您必须传入 --env。

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`	—	从该环境变量读取值

# 创建或更新您的 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 会提示确认。

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	—	跳过确认提示

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]`	查看数据集的生命周期日志（按时间顺序）

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 可继续向前翻页。

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

train

提交并管理当前 workspace repository 的训练任务。

train submit

osmosis train submit <config_path> [--yes]

Argument / Option	Type	Description
`config_path`	`path` (required)	`configs/training/` 下的 training TOML
`-y`, `--yes`	flag	跳过确认提示

Config 值来自本地 TOML 文件。训练代码来自已同步的 workspace repository。

train info

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

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

train logs

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

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 命令

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）。

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）。

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

--json 输出对两个列表分别使用不同的 key，结构本身即可表明各列表的归属：

{
  "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 可用时的部署状态。

osmosis model info <lora-model>

model deploy

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

osmosis model deploy <lora-model>

model undeploy

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

osmosis model undeploy <lora-model>

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

upgrade

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

osmosis upgrade

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

​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

​其他 train 命令

​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

其他 train 命令

model

model list

model info

model deploy

model undeploy

upgrade