Osmosis CLI Overview

The osmosis CLI is the command-line interface for the Osmosis AI Platform. Use it to authenticate, resolve a workspace from Git or an explicit workspace name, manage datasets and models, run evaluations locally, upload completed local results, and submit managed evaluation, training, and benchmark runs. It ships in the same osmosis-ai Python package as the open source SDK.

Start Here

Install and authenticate

Install the CLI, verify its version, and sign in. CI can use OSMOSIS_TOKEN instead of an interactive login.

python -m pip install "osmosis-ai>=0.3.0,<0.4"
osmosis --version
osmosis auth login

Choose workspace scope

By default, Platform commands resolve their workspace from the current repository’s Git origin. For platform-only work from another directory, pass root --workspace <workspace-name> to select an exact workspace by name.

Choose a run workflow

Run a rollout evaluation locally for fast iteration, use a managed full-size evaluation before training, or run a published benchmark to compare agents independently of workspace rollout code.

Run Workloads

Evaluation

Test a rollout and grader locally or on managed infrastructure.

Training

Train a base model with a validated rollout and dataset.

Benchmarks

Compare agents on published task sets and environments.

Command Areas

Area	Use it to
`auth`	Log in, log out, and inspect the current identity.
`doctor`	Inspect and repair the canonical workspace directory scaffold.
`dataset`	Validate, upload, preview, download, and inspect datasets.
`eval`	Run evaluations locally, upload completed local results, and submit, inspect, stop, or download platform evaluation runs; run local rubric scoring.
`train`	Submit, inspect, stop, and view logs for training runs.
`benchmark`	Discover benchmarks and submit, inspect, stop, or download benchmark runs.
`rollout`	Scaffold and list rollouts in the current workspace.
`model`	List, inspect, deploy, and undeploy models.
`secret`	Create and inspect personal or workspace secret records.
`template`	List and apply workspace templates.
`upgrade`	Upgrade the CLI to the latest published version.

See the Command Reference for every command and option.

Workspace Scope

Without an explicit selector, Platform commands retain the current repository’s Git-derived scope. Root --workspace selects an exact platform workspace and sends workspace-name scope instead of Git scope:

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

No local repository is required with explicit scope for the complete benchmark catalog, submit, and run family; platform dataset, model, and secret commands; or train / eval list, info, logs, and stop. eval submit and train submit can also start from any current directory when you pass an absolute config path under the source repository’s canonical configs/eval/ or configs/training/ directory. The CLI locates that repository and verifies it matches the selected workspace before submitting. In structured output, explicit platform-only scope reports workspace.name and does not fabricate git or workspace_directory fields. Source-backed eval and training submissions may also report the real local Git context found from the config path.

Repository Inputs

Local eval run uses rollout code on disk. Managed evaluation and training use rollout code from the synced repository. Benchmark configs select published benchmark environments, do not reference workspace rollout code, and can be submitted from any readable TOML path.

repository/
├── rollouts/
│   └── my-rollout/
│       ├── main.py
│       └── pyproject.toml
└── configs/
    ├── eval/my-rollout.toml
    ├── training/my-rollout.toml
    └── benchmark/my-benchmark.toml

Use Workspace for the repository contract and Config Files for the TOML schemas.

Automation and Output

Global --json and --plain flags work before or after a command. Use --json for stable machine-readable envelopes, --yes only after reviewing a destructive or paid operation, and OSMOSIS_TOKEN for non-interactive authentication.

osmosis --json train info <run-name>
osmosis benchmark submit <config-path> --yes

For per-run credentials, use --secrets-file, process environment variables, stored Platform secret records, or the hidden terminal prompt. Never place secret values directly in command arguments or committed TOML files.

Next Steps

Installation & Authentication

Install the current CLI and configure local or CI authentication.

Workspace

Understand repository structure, Git scope, and validation.

Command Reference

Review every command, option, and output contract.

Config Files

Configure evaluation, training, and benchmark runs.

Get started

Runs

Workspace

Reference

Start Here

Run Workloads

Evaluation

Training

Benchmarks

Command Areas

Workspace Scope

Repository Inputs

Automation and Output

Next Steps

Installation & Authentication

Workspace

Command Reference

Config Files

​Start Here

​Run Workloads

Evaluation

Training

Benchmarks

​Command Areas

​Workspace Scope

​Repository Inputs

​Automation and Output

​Next Steps

Installation & Authentication

Workspace

Command Reference

Config Files

Start Here

Run Workloads

Command Areas

Workspace Scope

Repository Inputs

Automation and Output

Next Steps