Osmosis CLI 命令参考 - Osmosis AI Docs

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

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

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

Workspace scope

默认情况下，workspace-scoped Platform commands 从当前 repository 的 Git origin 派生 scope。Root option --workspace <workspace-name> 会改为按名称精确选择 platform workspace，并且只发送 X-Osmosis-Workspace，绝不会同时发送 X-Osmosis-Git：

osmosis --workspace <workspace-name> --json dataset list
osmosis --workspace <workspace-name> benchmark runs info <run-name>

使用显式 scope 时，完整 benchmark catalog、submit 和 run 命令族、platform dataset/model/secret commands，以及 train 的 list、info、logs 和 stop、eval 的 list、info、logs、retry 和 stop 都不需要本地 repository。不使用 --workspace 时，这些命令保留 Git-derived scope。eval run、eval upload、eval download 和 rollout 命令不在此列：它们都会读写以 workspace 为相对根的磁盘布局，因此即使设置了 --workspace，仍会从当前 repository 解析 workspace。当 config_path 是绝对路径时，source-backed eval submit 和 train submit 也可以从任意当前目录接受 root --workspace。Config 仍必须位于其所在 Osmosis Git workspace 的标准 configs/eval/ 或 configs/training/ 目录下。CLI 会定位该 repository，验证所选 workspace 已连接到它，并且只使用 workspace-name scope 提交。显式 platform-only scope 下的 structured result 包含 workspace.name，且不会编造 git 和 workspace_directory 字段。Source-backed eval 和 training submit 还可能包含从 config 路径解析出的真实本地 Git context。

环境变量

CLI 会从当前目录向上查找并加载最近的 .env 文件，然后再读取这些变量。非空的 process variables 优先于 dotenv 值。使用 root option --env-file <path>（或 OSMOSIS_ENV_FILE）可指定文件，使用 --platform <url> 可仅为一条命令覆盖 active platform。

变量	用途
`OSMOSIS_TOKEN`	使用非交互式认证替代已存凭证；设置后会禁用 `osmosis auth login`
`OSMOSIS_TOKEN_PLATFORM_URL`	将 `OSMOSIS_TOKEN` 绑定到目标 platform；active platform 不是默认 production platform 时必需
`OSMOSIS_TOKEN_STORE`	选择新持久登录的存储位置：`auto`（默认；keyring 加文件回退）、`keyring`（强制要求 keyring）或 `file`（保存到 `~/.config/osmosis/credentials.json`）
`OSMOSIS_PLATFORM_URL`	覆盖 Platform base URL；无 scheme 的 loopback host 使用 HTTP，其他 host 使用 HTTPS
`OSMOSIS_ENV_FILE`	指定 dotenv 文件，替代自动发现最近的 `.env`
`OSMOSIS_ALLOW_INSECURE_PLATFORM_URL`	设为 `1` 可允许非 HTTPS、非 loopback 的 platform URL；否则 CLI 会 fail closed
`OSMOSIS_DEBUG`	设为 `1` 可在意外 `INTERNAL` error 后附加原始 exception 和 traceback，同时保持 JSON envelope 不变

export OSMOSIS_TOKEN="<token>"
export OSMOSIS_PLATFORM_URL="<non-production-platform-url>"
export OSMOSIS_TOKEN_PLATFORM_URL="$OSMOSIS_PLATFORM_URL"
osmosis --json auth whoami

quickstart

交互式设置：登录、clone 您的 workspace，并获得第一段 agent prompt。

osmosis quickstart [--workspace NAME]

选项	类型	默认值	说明
`-w`, `--workspace`	`str`	当前 clone，否则提示选择	要设置的 workspace 名称

Wizard 会认证 CLI、解析要使用的 workspace、等待 workspace repository 连接并 clone 它、报告 billing 是否已设置，然后询问您想做什么。训练模型、在数据集上评估模型和运行 benchmark 这三项都会针对该目标打印一段 agent prompt；选择先探索则改为打印文档链接。在 workspace clone 内运行 osmosis quickstart 时，wizard 会通过 git remote 识别出该 workspace。在空目录或无关目录中运行时，它会列出您所属的所有 workspaces 并请您选择一个。使用 --workspace <name> 可跳过选择器，直接按名称指定 workspace。当您属于多个 workspaces 时这会很有用。它可以安全地重复运行：每一步都会先检查当前状态再做修改，因此对已经配置好的 workspace，它会给出一份全部通过的检查报告，然后直接询问您接下来想做什么。从空目录再次运行时，它会复用为该 workspace 记录的上一次 clone 路径（前提是该路径仍然存在）。Wizard 需要交互式终端，且只以 rich 输出模式运行，因此无法配合 --json 或 --plain 使用 —— 它自动完成的手动步骤参见 Onboarding。

auth

管理 CLI 认证。

命令	说明
`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 之外，或该仓库未链接到 Platform workspace 时，workspace 为 null，其余输出不变。该命令始终会向 Platform 校验本地凭证或 OSMOSIS_TOKEN，因此需要网络连接；未登录或 session 过期时会以 AUTH_REQUIRED 失败。持久凭证以 normalized platform URL 为 key，因此多个 platform environment 的登录可以共存。新登录优先使用 operating-system keyring；无法使用时回退到仅授予文件所有者读写权限的 ~/.config/osmosis/credentials.json，并打印 KEYRING_UNAVAILABLE 警告。设置 OSMOSIS_TOKEN_STORE=keyring 可强制使用 keyring 存储，或设置 OSMOSIS_TOKEN_STORE=file 将新登录保存到文件。已有凭证仍使用记录的 backend。运行 osmosis auth whoami 可查看有效的凭证来源以及持久登录所用的 backend。显式运行 osmosis auth login 替换登录或运行 osmosis auth logout 时，已存凭证才会发生变化；HTTP 401 只会报告 session 已过期或被撤销，不会删除本地状态。当 OSMOSIS_TOKEN 指向 non-production platform 时，请用 OSMOSIS_TOKEN_PLATFORM_URL 绑定它。Binding 缺失或不匹配时，CLI 会在任何 network request 之前以 ENV_TOKEN_PLATFORM_REQUIRED 或 ENV_TOKEN_PLATFORM_MISMATCH 失败。完整设置参见安装与认证。

doctor

检查并可选修复 workspace directory scaffold。

osmosis doctor [path] [--fix]

参数 / 选项	类型	默认值	说明
`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]

参数 / 选项	类型	说明
`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

参数 / 选项	类型	说明
`name`	`str` (required)	以小写字母开头，后续仅使用小写字母、数字或 hyphens 的 rollout name。`default` 为保留名称。
`-f`, `--force`	flag	替换该 rollout 的已有 scaffold paths

rollout list

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

选项	类型	默认值	说明
`--limit`	`int`	`50`	最多显示的 rollouts 数量
`--all`	flag	—	显示所有 rollouts
`--branch`	`str`	Repository default	显示从该分支同步的 rollouts

eval

在本地运行 evaluations、发布已完成的本地结果、提交并管理 platform evaluation runs，并在本地运行 LLM-as-judge rubric 评分。

eval run

通过当前 workspace rollout server entrypoint 构建的 backend（LocalBackend 或 Harbor）在本地执行 evaluation。该命令需要有效的本地 workspace，并安装 python -m pip install "osmosis-ai[eval]>=0.3.4,<0.4"。使用 --dataset-file PATH 且不带 --upload 时，命令不需要 platform credentials。选择 config 中命名的 platform dataset 或添加 --upload 时，仍需要已认证的 Git workspace context。Provider credentials 从 process environment 或 --secrets-file 解析；--secrets-file 中的值仅对本次 run 生效并优先于 process environment，退出时会恢复原有 environment。

osmosis eval run <config_path> [--name NAME] [--output PATH] [--dataset-file PATH] [--secrets-file PATH] [--rows ROWS] [--fresh] [--retry-failed] [--max-in-flight N] [--yes] [--tunnel PROVIDER] [--rollout-port PORT] [--listener-port PORT] [--advertise-url URL] [--verbose] [--upload]

参数 / 选项	类型	说明
`config_path`	`path` (required)	`configs/eval/` 下的 Eval TOML
`--name`	`str`	要恢复的既有 run name；省略时生成 `adjective-animal-number` 名称
`-o`, `--output`	`path`	Run output root；默认为 `.osmosis/evals/`
`--dataset-file`	`path`	替代 platform dataset 的本地 dataset 文件
`--secrets-file`	`path`	提供 `[secrets].required` 值的 dotenv 文件；`-` 表示从 stdin 读取
`--rows`	`str`	Dataset rows，例如 `3,7,10-20`；覆盖 `limit`
`--fresh`	flag	归档该 run name 的现有结果并重新开始
`--retry-failed`	flag	重试 failed 和 skipped work items，并保留 successes
`--max-in-flight`	`int`	Concurrent rollouts；依次默认使用 `evaluation.batch_size`、backend capacity、`1`
`-y`, `--yes`	flag	跳过 local-run confirmation prompt
`--tunnel`	`str`	不依赖自动检测，为 model bridge 强制使用托管 tunnel；provider 仅支持 `cloudflared`。仅当 rollout server 自身不上报该需求时才需要，例如第三方 backend
`--rollout-port`	`int`	固定 rollout-server port；默认使用 ephemeral port
`--listener-port`	`int`	固定 model-bridge listener 的本地端口；默认使用 ephemeral port
`--advertise-url`	`str`	您自行运行且已能访问 listener 的 tunnel 公网 base URL；需要配合 `--listener-port`，且不能与 `--tunnel` 同时使用
`--verbose`	flag	流式输出 supervisor 和 rollout-server logs
`--upload`	flag	Run 达到完整 terminal 状态后发布

Failed 和 skipped samples 属于 terminal 状态，可以上传。Pending 和 cancelled runs 不能上传。--upload 使用同一个 local run lock，并且仅在完成后开始发布。输出写入 .osmosis/evals/<run-name>/，其中 metrics.json、summary.jsonl、trajectories/ 和 artifacts/ 与 eval download 使用相同结构，并额外包含 canonical rollout_trials/<rollout-id>/ store 和一个 logs.txt，其中已配置的 [secrets] 值以及 process environment 中长度至少为 8 个字符的已知 provider 和 platform key 值均已被 redact。重复使用同一个 --name 时，只会恢复没有 durable terminal result 的工作。如果该 named run 已完成，交互式命令会建议启动一个新生成名称的 run；拒绝、--yes 和非交互模式都不会修改它，并会打印 next steps。Named run 会锁定 model、dataset bytes、selected rows、n、timeouts、pass threshold、entrypoint 和 rollout source digest；输入变化时会拒绝恢复。使用 --fresh 可归档旧目录并重新开始——既有结果会移动到 .osmosis/evals/<run-name>.archive-<utc-timestamp>/，且永不删除；在不改代码的情况下，使用 --retry-failed 可重试 failed 和 skipped items，同时保留 successes。恢复以 journal 为依据。通过长轮询返回的 terminal 结果会追加到 events.jsonl 并执行 fsync，然后才计入已完成的本地工作。中断后，没有持久 terminal 记录的工作仍处于 pending 状态，可以再次运行。 Rollout server 通过 uv 在 rollouts/<name>/pyproject.toml 解析出的环境中运行，而不是在 CLI environment 中运行。请将 CLI 和该 rollout dependency 一起升级到 0.3.x 系列的 0.3.3 或更高版本；CLI 和 server 都必须使用 0.3.3 引入的长轮询协议。请在该文件中声明 Harbor 和其他 rollout-side dependencies。ROLLOUT_SDK_VERSION_MISMATCH warning 只表示已安装版本不同，并不证明协议兼容。使用先前 callback 协议创建的本地 run 无法在 0.3.3 下恢复：请使用新名称，或使用 --fresh 归档后重新开始。参见 0.3.3 迁移指南。无法访问本机 loopback interface 的 Harbor sandbox（Daytona，以及 macOS 之外的 Docker）需要一个公网 URL 才能访问本地 model bridge。CLI 会从 rollout server 的 health 报告中读取该需求，并自动启动托管的 cloudflared quick tunnel，因此请把该 binary 保留在 PATH 中。不上报该需求的 rollout server（例如第三方 backend）需要使用 --tunnel cloudflared 强制启动 tunnel，或使用 --advertise-url 配合 --listener-port 使用您自行运行的 tunnel。启动时会先校验 model 和 rollout server，然后才打开 tunnel；当 tunnel 始终不可达或中途退出时，run 会报错停止而不是挂起。只有 sandbox 的 OpenAI-compatible chat 流量会经过 tunnel。Rollout 结果通过 loopback 上的长轮询收集。Model-bridge listener 不提供 docs 或 OpenAPI surface；其 chat routes 需要每次 run 重新生成的 bearer token，由 bridge 向上游提供 provider credentials。仅访问 tunnel URL 会得到 404，启动时也用它来探测 tunnel 是否就绪；当该探测无法完成时，run 会给出 warning 并依据 cloudflared 自身的 connection registration 信号继续，因为 sandbox 可能可以解析该 host，而您的网络不行。运行 allowlist egress 的 Harbor task 会自动把 tunnel host 加入其 allowlist。 Tunnel 模式还会在 bridge 的非 streaming 路径上启用 keepalive，因为 proxy edge 会切断长时间静默的 origin——cloudflared quick tunnel 两次读取之间约允许 125 秒。经过 90 秒的宽限窗口后，bridge 会先提交 200 application/json，随后每 30 秒发出一个空白字节，直到真正的 body 到达，从而避免缓慢的 model 调用被中途切断。代价是：在该窗口之后发生的 provider error 会以 200 状态下的 OpenAI 风格 {"error": ...} body 返回，而不是非 2xx 响应。 Cloudflare 限制的是每个来源 IP 创建 quick tunnel 的速率，而不是 tunnel 流量，因此同一台机器上大量短 run 可能开始以 429 失败，而已经运行的 tunnel 仍可正常服务。请等待几分钟，或使用 --advertise-url 指向您自行运行的 tunnel。当前限制请参见 Cloudflare 的 quick tunnel 文档。

没有 local-only config section，因此同一个 evaluation TOML 可同时用于 eval run 和 eval submit。Harbor rollout 的 environment selection 位于 entrypoint 中，在 local eval 中同样直接生效。

osmosis eval run configs/eval/my-rollout.toml
osmosis eval run configs/eval/my-rollout.toml --upload

eval upload

发布已完成且兼容的本地 evaluation run。该命令不需要 confirmation。

osmosis eval upload <eval-name-or-directory> [--replace]

参数 / 选项	类型	说明
`eval_name_or_directory`	`path` (required)	已完成的本地 run name（在 workspace 的 `.osmosis/evals/` 下解析），或显式的 run directory，例如 `.osmosis/evals/<run-name>/`
`--replace`	flag	替换该 run 已发布的结果，用于以 `--retry-failed` 重跑过的 run

仅给出 run name 时会解析为 workspace directory 下的 .osmosis/evals/<run-name>/；如果当前目录已存在同名目录，则优先使用该目录，而任何带分隔符的相对或绝对路径都按给定值使用。该目录必须包含兼容的 manifest.json、index.jsonl、progress.json 和 metrics.json 文件，并且命令需要已认证的 workspace context。上传是 idempotent 且以 server 为准：中断后再次运行同一命令，会返回相同的 platform run，并仅上传 server 仍缺少的文件。 Upload 会发送 index.jsonl、progress.json、合并的 logs.txt（如果存在），以及仅由所选 rollout IDs 引用的 canonical trajectory*.json 文件与 safe artifacts。它不会发送本地 manifest.json bytes、events.jsonl、metrics.json、summary 或 projection copies、control files、per-trial logs 或 superseded attempts。上传前会使用当前 process environment 中长度至少为 8 个字符的已知 provider 和 platform key 值对 logs.txt 再次脱敏，然后计算文件 hash。这无法检测任意 secret 或已不在当前 environment 中的旧凭证；参见日志脱敏。Manifest digest、schema versions 和 allowlisted redacted Git provenance 会作为 metadata 发送；server 会严格校验文件、重新计算 metrics，并且不会启动 hosted 或 Temporal evaluation work。恢复一次被中断的上传不需要 --replace：它会返回相同的 platform run，并仅发送仍缺少的文件。--replace 用于为一个已完成导入的 run 发布另一份结果，否则会返回 conflict 而不是覆盖它。在 --retry-failed 之后传入 --replace，即可原地替换该 run 已发布的结果；platform run 会保留其 ID 和 URL，且 manifest digest 仍必须匹配，这正是两次 attempt 评估了相同已解析输入的证明。eval run --retry-failed --upload 会自动设置该 flag。

osmosis eval upload <run-name>
osmosis eval upload .osmosis/evals/<run-name>/
osmosis eval upload <run-name> --replace

eval submit

从 source repository 的 configs/eval/ 下的 TOML config 在 managed infrastructure 上创建并运行 evaluation。通常，平台会克隆由当前 Git origin 标识的 workspace repository。使用 root --workspace 时，请传入绝对的标准 config 路径；CLI 会验证其 repository 与所选 workspace 匹配。请在提交前 push commits。

osmosis eval submit <config_path> [--yes] [--secrets-file PATH]

参数 / 选项	类型	说明
`config_path`	`path` (required)	Source repository 的 `configs/eval/` 下的 eval TOML；设置 root `--workspace` 时必须是绝对路径
`-y`, `--yes`	flag	跳过确认提示
`--secrets-file`	`path`	为 `[secrets].required` 名称提供值的 dotenv 文件；`-` 表示从 stdin 读取

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

# 从其他当前目录提交同一个 source-backed config
osmosis --workspace my-workspace eval submit /absolute/path/to/repository/configs/eval/my-rollout.toml

# 无需保存到 secret store，即可为本次运行提供 secret 值
osmosis eval submit configs/eval/my-rollout.toml --secrets-file .env.run
vault read -field=env secret/eval | osmosis eval submit configs/eval/my-rollout.toml --secrets-file - --yes

[secrets].required 中的每个名称按以下顺序解析：--secrets-file、CLI 进程环境变量、已有 personal 或 workspace secret，最后才是在 stdin 为 TTY 时显示的隐藏 prompt。已有存储值由服务端解析。通过文件、环境变量或 prompt 在本地提供的值会随本次提交的 TLS 请求发送，但不会加入 Osmosis secret store 或持久化 run config，因此后续运行仍需重新提供。在非 TTY 环境下，经过 stored-secret 检查后仍未解析的名称会一次性报告，便于 CI 展示完整缺口。详见 [env] 和 [secrets]。

Config 值来自本地 TOML 文件。Rollout 代码来自已同步的 workspace repository。使用 [experiment].branch 或 [experiment].commit_sha 选择代码来源；二者互斥。

上传的本地 runs 也会显示在 eval list、eval info 和 Platform viewers 中，并带有 Local badge；dirty Git provenance 会显示 warning。上传的本地 run 不能替代训练前要求的 managed full-size evaluation gate。

eval list

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

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

选项	类型	默认值	说明
`--limit`	`int`	`50`	最多显示的 evaluation runs 数量
`--all`	flag	—	显示所有 evaluation runs

eval info

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

osmosis eval info <run-name> [--output PATH]

参数 / 选项	类型	说明
`name_or_id`	`str` (required)	evaluation run 名称或 ID
`-o`, `--output`	`path`	run 输出根目录。rich 模式下默认为 `.osmosis/evals/<name>/`。

详情字段显示 name、status、进度（已完成行数和百分比）、耗时、pass rate、tokens 使用量、提交与完成时间，以及该 run 使用的 dataset、model 和 rollout。其后是两个 section：

Configuration — entrypoint、解析后的 config 值（limit、n、batch_size、pass_threshold、各项超时）、branch、短 commit SHA、已解析的 secret scope，以及 [env] 键。
Results — graded、passed、failed、skipped 计数，pass 阈值，reward 统计（mean、std、min、median、max），以及 pass@k。

eval info 只报告聚合结果。平台日志请使用 eval logs，逐行 trajectory、artifact、metrics 和日志请使用 eval download。对于已完成的 run，eval info 还会从平台拉取 metrics（耗时、pass rate、tokens 使用量、reward 统计、pass@k），并导出为 JSON：

在 rich 模式下，若 metrics 可用，CLI 会默认将其保存到 .osmosis/evals/<name>/metrics.json。
在 JSON 或 plain 模式下，使用 -o / --output 指定 run 输出根目录；CLI 会在该目录下写入 metrics.json。
CLI 会自动创建上级目录。
若 metrics 尚不可用（例如 run 仍处于 pending 状态），CLI 会打印提示，而不会写入文件。

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

-o / --output 现在指向 run 输出根目录，而不是 metrics 文件名。.osmosis/metrics/ 下的旧文件不会被删除——在新布局下重新运行 eval info 后，请手动清理。

eval download

将 evaluation run 的输出（metrics、trajectories、artifacts、logs）从平台下载到本地磁盘。

osmosis eval download <run-name> [--type TYPES] [--rows ROWS] [--output PATH] [--overwrite] [--yes]

参数 / 选项	类型	默认值	说明
`name_or_id`	`str` (required)	—	evaluation run 名称或 ID
`--type`	`str`	`metrics,trajectories`	逗号分隔的选择器：`metrics`、`trajectories`、`artifacts`、`logs` 或 `all`。会替换默认选择。
`--rows`	`str`	—	用于 trajectories 与 artifacts 的行选择，例如 `3,7,10-20`。所选行的所有 run 都会包含。
`-o`, `--output`	`path`	`.osmosis/evals/<name>/`	run 输出根目录。目录下的文件名与子目录固定。
`--overwrite`	flag	—	重新下载本地已存在且大小匹配的文件。
`-y`, `--yes`	flag	—	跳过下载超过 100 MiB 时的确认提示。

文件会落到一份固定的、按 run 划分的目录结构下，便于重复运行时断点续传：

.osmosis/evals/<run-name>/
├── metrics.json
├── summary.jsonl
├── trajectories/row_<row>_run_<n>.json
├── artifacts/row_<row>_run_<n>/...
└── logs.txt

行为：

本地大小与平台 manifest 一致的文件会被跳过，除非传入 --overwrite。因此重新执行命令只会拉取缺失或未完成的文件。
总下载量超过 100 MiB 时需要确认；在脚本中可用 --yes 跳过提示。
预签名 URL 会按批请求，最多同时下载 8 个文件。每个文件先写入 *.partial，在校验大小后原子性移动到位。
失败的文件会带指数退避重试。若仍有文件失败，CLI 会列出每个失败路径并以 partial 状态退出——再次运行命令即可只重试缺失的部分。
pending 状态的 run 会提前失败并给出明确提示；平台负责权威的路径校验。

# 默认：下载整个 run 的 metrics 与 trajectories
osmosis eval download my-eval-run

# 只下载第 3、7 行和第 10–20 行的 artifacts
osmosis eval download my-eval-run --type artifacts --rows 3,7,10-20

# 下载所有内容到自定义根目录，非交互模式
osmosis eval download my-eval-run --type all -o ./eval-outputs/ --yes

eval retry

重新运行 managed evaluation run 中 failed 和 skipped 的 samples。已评分的 samples 会保留：该 run 会基于自身的 sample index、在同一 run ID 下恢复，因此只有未评分的行会再次执行。

osmosis eval retry <run-name> [--yes] [--secrets-file PATH]

参数 / 选项	类型	说明
`name_or_id`	`str` (required)	evaluation run 名称或 ID
`-y`, `--yes`	flag	跳过确认提示
`--secrets-file`	`path`	提供原始 run 自行传入的 secret 值的 dotenv 文件；`-` 表示读取 stdin。这些值不会被保存

该 run 必须处于 finished、failed 或 stopped 状态，并且至少有一个未评分的 sample。已评分的 sample 会被保留且永不重跑，即使其 reward 低于 pass threshold。重试会针对提交时的同一 model、dataset 和 commit 重新执行，计费方式与新提交相同，并作为独立的 attempt 计量。如果原始 run 自行提供了 secret 值，这些值从不存储。Platform 会返回它需要的名称，CLI 会依次从 --secrets-file、环境变量或交互式提示中解析，然后再发起重试。这些值仅随本次请求发送，并会从 Platform 返回的任何校验错误中被脱敏。Local run 在产生它的机器上重试：该命令不会发起重试，而是打印对应的 eval run --retry-failed --upload 调用，其中的 config 路径取自该 run 的 provenance。参见 eval run --retry-failed。

osmosis eval retry my-eval-run --yes
osmosis eval retry my-eval-run --secrets-file .env.run

eval stop

停止一次 pending 或 running 的 evaluation run。

osmosis eval stop <run-name> [--yes]

参数 / 选项	类型	说明
`name_or_id`	`str` (required)	evaluation run 名称或 ID
`-y`, `--yes`	flag	跳过确认提示

eval logs

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

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

参数 / 选项	类型	默认值	说明
`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>

选项	类型	默认值	说明
`-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`	—	已弃用；请改用 provider 的环境变量。该 flag 仍可用，但会输出 `DEPRECATION` warning。
`--timeout`	`float`	—	request timeout，单位秒
`--score-min`	`float`	`0.0`	最小分数
`--score-max`	`float`	`1.0`	最大分数

benchmark

查看所选 workspace 中的托管 benchmark，并提交、查看和管理 benchmark runs。设置 root --workspace 后，完整命令族无需本地 repository 即可工作。benchmark list 和 benchmark info 作用于 benchmark 本身，即 workspace 列表和单个 benchmark 的页面。针对单个 run 的命令位于 benchmark runs 之下。

benchmark list

列出已经添加到当前 workspace 的 benchmark。

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

选项	类型	默认值	说明
`--limit`	`int`	`50`	最多显示的 benchmark 数量
`--all`	flag	关闭	获取全部 benchmark

表格显示 Name、对 shell 友好的 Key、Last Run 和 Tasks。Last Run 显示最新 run 的状态、距今时长和名称（Finished · 2d ago · brave-otter）。key、区分大小写的准确名称和 ID 都可用于 [experiment].benchmark。JSON 列表项包含 run_count、running_count、last_run_at、last_run_status、last_run_name 和 creator_name。 Harbor registry benchmark 在被添加后，其 task 列表才会从 registry 分页同步进来。同步完成前，Last Run 显示同步状态而不是 run（Syncing · 412 / 500 tasks），Tasks 列留空，并且无法针对它提交 run。同步失败的 benchmark 会在 Last Run 中说明原因，在 Tasks 列显示 unavailable，并返回 sync_error；请在 Platform 的该 benchmark 页面上重试同步。返回的 platform_url 会打开该页面，其中包含它的 leaderboard 和 runs。

benchmark info

显示 benchmark 的摘要、leaderboard 和 runs。

osmosis benchmark info <key_name_or_id> [--limit N] [--all]

参数 / 选项	类型	默认值	说明
`key_name_or_id`	`str`（必需）	—	Benchmark 的 key、准确名称或 ID
`--limit`	`int`	`50`	Runs 表格最多显示的 run 数量
`--all`	flag	关闭	在 runs 表格中显示全部 run

普通输出先显示 benchmark 摘要（source 的上游页面地址、runner、task 和 category 数量、命名 task set、harness 与 judge 要求，以及 pass threshold），随后是该 benchmark 的 leaderboard 和 workspace 在其上的 runs 表格。--limit 和 --all 作用于 runs 表格。若某个 benchmark 的公开分数是在特定 harness 上测得的，该 harness 会作为默认值一并显示。LLM Judge 行在由 run 选择 judge model 时显示 Required (default: <model>)，在 adapter 固定自身 grader、run 只需提供 judge_api_key_secret 时显示 API key only (pinned grader)，在 benchmark 不使用 judge 时显示 –。JSON 输出还会包含完整 task manifest 和 leaderboard 数组：

osmosis --json benchmark info terminal-bench-2-1

每个 leaderboard 条目包含排名和 tied 标志（当配对检验无法将该 entrant 与排名第一的 entrant 区分时置位，此时它与其并列第 1）。它还会给出 task set（full 或 parity）、harness 和 model，以及产生该成绩的 run 的 id、name 和 platform_url。随后是五项排序指标：带置信区间的 pass_at_1、pass_at_k、按 task 计的 cost_per_task、mean_duration_seconds 和 tokens_per_task。这与 Platform leaderboard 的排序指标相同。 JSON manifest 中的每个 task 都有 difficulty 字段，值为 easy、medium、hard 或 null。null 表示 source 未提供难度，客户端绝不能自行推断。对于 HLE，benchmark info 还会把 parity 标记为推荐的命名 task set。Config 中省略 [tasks] 会选择完整 benchmark；如需子集，请使用 task_names、categories 或列出的 task_set。

benchmark submit

从任意可读的 Osmosis TOML config 路径提交 benchmark run。将 config 保存在 configs/benchmark/ 下是 repository convention，不是 CLI 要求。

osmosis benchmark submit <config_path> [--yes] [--secrets-file PATH]

参数 / 选项	类型	说明
`config_path`	`path`（必需）	任意可读的 benchmark TOML 文件
`-y`, `--yes`	flag	跳过确认提示
`--secrets-file`	`path`	为 `[secrets].required` 名称提供值的 dotenv 文件；`-` 表示从 stdin 读取

osmosis benchmark submit configs/benchmark/terminal-bench-smoke.toml

# 无需保存到 secret store，即可为本次运行提供 token
osmosis benchmark submit configs/benchmark/hle-parity.toml --secrets-file .env.run

[experiment].benchmark 指定的 benchmark 必须已经添加到所选 workspace。命令会在提交前预览选中的 tasks、agents、尝试次数、并发数和解析后的 secret scopes。[secrets].required 名称使用与 eval 和 training 相同的文件 → 进程环境变量 → 已存 personal/workspace secret → 隐藏 TTY prompt 顺序。本地提供的值会标记为 Run，并随本次提交的 TLS 请求传输，但不会加入 Osmosis secret store 或持久化 run config；已存值由服务端解析。其他所有 secret 引用（model 的 api_key_secret、harness_api_key_secret、judge_api_key_secret、[verifier].required）必须已存在于 workspace 或 personal scope 中。结果包含生成的 run 名称、task 数量、状态、platform_url 和所选 workspace context。 CLI workflow 参见 Benchmarks，完整 TOML schema 参见配置文件。

benchmark runs list

列出当前 workspace 的 benchmark runs。表格与 Platform 的 runs 表格一致：Name、Status、Progress、Benchmark、Agents、Best Pass@1、Submitted 和 Submitted By。

osmosis benchmark runs list [--limit N] [--all]

选项	类型	默认值	说明
`--limit`	`int`	`50`	最多显示的 benchmark run 数量
`--all`	flag	—	显示所有 benchmark runs

benchmark runs info

显示 benchmark run 的配置、agents、进度、result totals 和 metrics。

osmosis benchmark runs info <run-name>

参数	类型	说明
`name_or_id`	`str`（必需）	Benchmark run 名称或 ID

摘要显示状态、进度、时长、best pass@1 和提交信息。Agents 部分按 run 页面 Agent Results 表格的方式为每个 agent 打分：排名、带区间的 pass@1、最深的 pass@k，以及按 task 计的 cost、time 和 tokens。Results totals 显示各类结果数量、input 与 output token，以及 LLM Cost；后者是使用您自己 provider key 产生的模型花费，不由 Osmosis 计费。结果中包含 platform_url，可用于在 Platform 中打开该 run。

benchmark runs logs

按时间顺序（从最早开始）显示 benchmark run 的最近生命周期日志。可用于监控进度和诊断失败。

osmosis benchmark runs logs <run-name> [--limit N] [--cursor CURSOR]

参数 / 选项	类型	默认值	说明
`name_or_id`	`str`（必需）	—	Benchmark run 名称或 ID
`--limit`	`int`	`50`	每页条数（1–200）
`--cursor`	`str`	—	上一页 `next_cursor` 返回的游标

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

benchmark runs stop

停止 pending、queued 或 running 状态的 benchmark run。

osmosis benchmark runs stop <run-name> [--yes]

参数 / 选项	类型	说明
`name_or_id`	`str`（必需）	Benchmark run 名称或 ID
`-y`, `--yes`	flag	跳过确认提示

benchmark runs download

下载 benchmark summary metrics、task-level results、result artifacts 或 logs。

osmosis benchmark runs download <run-name> [--type TYPES] [--output PATH] [--overwrite] [--yes]

参数 / 选项	类型	默认值	说明
`name_or_id`	`str`（必需）	—	Benchmark run 名称或 ID
`--type`	`str`	`summary,results`	逗号分隔的选择器：`summary`、`results`、`artifacts`、`logs` 或 `all`。会替换默认选择。
`-o`, `--output`	`path`	`.osmosis/benchmarks/<name>/`	run 输出根目录。目录下的文件名与子目录固定。
`--overwrite`	flag	—	重新下载本地已存在且大小匹配的文件。
`-y`, `--yes`	flag	—	跳过大体积下载的确认提示。

下载使用固定的、按 run 划分的目录结构：

.osmosis/benchmarks/<run-name>/
├── summary.csv
├── results.csv
├── logs.txt
└── artifacts/<result-id>/<path>

除非传入 --overwrite，CLI 会跳过本地已完整下载的文件；未完成的下载会先写入临时文件再原子性移动到位。若重试后仍有文件失败，CLI 会报告这些文件；再次运行同一命令即可只获取缺失或未完成的文件。 pending 和 queued 状态的 run 尚无可下载输出。下载 running 状态的 run 会得到当前快照；使用 --overwrite 可刷新本地已有文件。

secret

管理 Platform environment_secret records。Train 和 eval config 通过 [secrets].required 引用这些 records。Benchmark config 会引用 model (api_key_secret)、harness (harness_api_key_secret) 和 judge (judge_api_key_secret) records，以及 [verifier].required 中列出的所有数据集校验器 records。Osmosis 从不向 CLI 返回 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]

选项	类型	默认值	说明
`--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]

参数 / 选项	类型	默认值	说明
`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]

参数 / 选项	类型	默认值	说明
`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 的平台数据集。Platform-backed commands 可在没有本地 repository 时接受 root --workspace；dataset validate 是本地命令，既不需要 workspace scope，也不需要 platform authentication。

命令	说明
`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

提交 source-backed training runs，并管理所选 workspace 的 runs。List、info、logs 和 stop 可在没有本地 repository 时接受 root --workspace。

train submit

osmosis train submit <config_path> [--yes] [--secrets-file PATH]

参数 / 选项	类型	说明
`config_path`	`path` (required)	`configs/training/` 下的 training TOML
`-y`, `--yes`	flag	跳过确认提示
`--secrets-file`	`path`	为 `[secrets].required` 名称提供值的 dotenv 文件；`-` 表示从 stdin 读取

使用 root --workspace 时，config_path 必须是其所在 repository 的 configs/training/ 目录下的绝对路径。CLI 会在提交前验证该 repository 已连接到所选 workspace：

osmosis --workspace <workspace-name> train submit /absolute/path/to/repository/configs/training/<name>.toml

Config 值来自本地 TOML 文件。训练代码来自已同步的 workspace repository。[secrets].required 名称使用 eval submit 中记录的文件 → 进程环境变量 → 已存 personal/workspace secret → 隐藏 TTY prompt 解析顺序；本地提供的值会随当前 TLS 请求传输，但不会加入 Osmosis secret store 或持久化 run config。

train info

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

显示训练任务详情、checkpoints 和 metrics。运行中和已结束的 run 都会列出可用 checkpoints；pending 和 queued runs 不显示 checkpoint 列表。运行过程中，summary 面板会显示进度（current_step / total_steps 及完成百分比）和最新的 reward。在 rich mode 下，metrics 默认保存到 .osmosis/metrics/。

train logs

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

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

参数 / 选项	类型	默认值	说明
`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 <run-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]

选项	类型	默认值	说明
`--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

显示单个 model 的详情。LoRA model 会显示 base model、training run、checkpoint step、training reward、Hugging Face 导出状态，以及 deployment info 可用时的部署状态。Base model 会显示其 Hugging Face path、parameters、context window、Hugging Face URL，以及该 model 已针对 inference 定价时的 inference price。

osmosis model info <model>

<model> 可以是 LoRA model name、base model name，或 base model 的 Hugging Face path（Qwen/Qwen3-4B）。Path 始终解析为 base model；name 会先尝试 LoRA model，再尝试 base model。如果两者都不匹配，CLI 会报告 Model not found: <model>。

osmosis model info qwen3-run1-step-100
osmosis model info Qwen/Qwen3-4B
osmosis --json model info Qwen/Qwen3-4B

--json 输出对 base model 使用 base_model 键，对 LoRA model 使用 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），并运行相应升级命令。

​Workspace scope

​环境变量

​quickstart

​auth

​doctor

​template

​template list

​template apply

​rollout

​rollout init

​rollout list

​eval

​eval run

​eval upload

​eval submit

​eval list

​eval info

​eval download

​eval retry

​eval stop

​eval logs

​eval rubric

​benchmark

​benchmark list

​benchmark info

​benchmark submit

​benchmark runs list

​benchmark runs info

​benchmark runs logs

​benchmark runs stop

​benchmark runs download

​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

Workspace scope

环境变量

quickstart

auth

doctor

template

template list

template apply

rollout

rollout init

rollout list

eval

eval run

eval upload

eval submit

eval list

eval info

eval download

eval retry

eval stop

eval logs

eval rubric

benchmark

benchmark list

benchmark info

benchmark submit

benchmark runs list

benchmark runs info

benchmark runs logs

benchmark runs stop

benchmark runs download

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