Skip to main content

​
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

​
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.
osmosis upgrade

​
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 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.