Skip to main content

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.

​
Installation

Install the Osmosis CLI from PyPI: 
pip install osmosis-ai
Python 3.12 or later is required. The package registers three equivalent CLI aliases: osmosis, osmosis-ai, and osmosis_ai.
Verify the installation: 
osmosis --version

​
Upgrading

The CLI can upgrade itself in-place. It auto-detects your install method (pip, pipx, or uv tool) and runs the appropriate upgrade command: 
osmosis upgrade
You can also upgrade manually with your package manager of choice:
pip install --upgrade osmosis-ai
# or
pipx upgrade osmosis-ai
# or
uv tool upgrade osmosis-ai

​
Authentication

​
Login

osmosis auth login
Opens a browser-based OAuth flow to authenticate your CLI session. Credentials are stored locally and reused for subsequent commands.
OptionDescription
-f, --forceForce re-login, clearing existing credentials
--token <TOKEN>Authenticate with a personal access token instead of browser flow (useful for CI/CD)
For CI/CD pipelines, set the OSMOSIS_TOKEN environment variable instead of running osmosis auth login. When this variable is set, the CLI uses it automatically and the login command is disabled.

​
Logout

osmosis auth logout
Revokes the current session and clears local credentials.
OptionDescription
-y, --yesSkip confirmation prompt

​
Who Am I

osmosis auth whoami
Displays the currently authenticated user, active workspace, and token expiration date.

​
Platform Workspace Context

All CLI operations are scoped to the active platform workspace. Platform workspaces are remote organizational spaces on the Osmosis platform for managing datasets, training runs, models, and team members.
Platform workspaces are distinct from local workspace directories created by osmosis init. A local workspace is a directory on your machine that contains your AgentWorkflows, Graders, configs, and datasets. See Workspace Overview for details on local workspace structure.

​
Interactive Browser

Running osmosis workspace without a subcommand launches an interactive TUI for browsing workspace contents: 
osmosis workspace

​
List Workspaces

osmosis workspace list
Lists all workspaces available to the authenticated user.

​
Create a Workspace

osmosis workspace create <name>
Argument / OptionDescription
name (required)Workspace name. Must be lowercase alphanumeric characters and hyphens only, max 64 characters.
--timezoneIANA timezone for the workspace (default: UTC). Example: America/New_York.

​
Switch Workspace

osmosis workspace switch <name>
ArgumentDescription
name (required)Name of the workspace to switch to

​
Delete a Workspace

osmosis workspace delete <name>
Argument / OptionDescription
name (required)Name of the workspace to delete
-y, --yesSkip confirmation prompt
Deleting a workspace stops all running processes and permanently removes all datasets, training runs, and models. This action cannot be undone. Only workspace owners can delete a workspace.

​
Next Steps

Command Reference

Full reference for every CLI command and its options.

Configuration Files

TOML config formats for training, eval, and serve.