Skip to main content

​
Installation

Install the Osmosis CLI from PyPI:
Python 3.12 or later is required. The package registers three equivalent CLI aliases: osmosis, osmosis-ai, and osmosis_ai.
Verify the installation:
The same package also provides the Python SDK. See SDK Installation for rollout dependencies, optional extras, and SDK verification.

​
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:
You can also upgrade manually with your package manager of choice:

​
Version Compatibility

The CLI sends its version to the platform on every request so the platform can signal when an upgrade is recommended or required:
  • Deprecation warning. If your installed version is approaching end of support, the CLI prints a one-time yellow ⚠ warning to stderr. Commands continue to run normally — schedule an upgrade at your convenience.
  • Upgrade required. If your version is below the minimum supported version, platform requests fail with an Upgrade required error and the command exits. Run osmosis upgrade (or the equivalent for your install method) to continue.

​
Authentication

​
Login

Opens a browser-based OAuth flow to authenticate your CLI session. Credentials are stored locally and reused for subsequent commands.
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

Revokes the current session and clears local credentials.

​
Who Am I

Displays the currently authenticated user and token expiration date.

​
Workspace Context

Most platform commands are scoped through the workspace repository you are currently inside. If you are setting up Osmosis for the first time, complete Onboarding before running workspace-scoped commands. For details on how the CLI reads GitHub origin and maps local commands to a platform workspace, see Workspace Repository.

​
Next Steps

Onboarding

Set up a workspace repository and local CLI context.

Command Reference

Full reference for every CLI command and its options.
Last modified on August 11, 2026