Skip to main content

​
Installation

Install the Osmosis CLI from PyPI:
Python 3.12 or later is required, and Python 3.12, 3.13, and 3.14 are supported. 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. The CLI prefers the operating-system keyring, keyed by the active platform URL, so logins survive across working directories, virtual environments, and uv run. Running auth login again safely replaces the saved login; the command no longer accepts --force.

​
Credential Storage Backends

By default (OSMOSIS_TOKEN_STORE=auto), the CLI tries to save your token in the operating-system keyring. If the keyring cannot be used, it falls back to ~/.config/osmosis/credentials.json and prints a KEYRING_UNAVAILABLE warning. The file is written atomically with owner-only permissions (0600 inside a 0700 directory). Run osmosis auth whoami to see the effective credential source and the backend of any persistent login. Set OSMOSIS_TOKEN_STORE to choose storage for new logins: Any other value fails with VALIDATION. This setting selects storage for new logins; it does not migrate existing credentials, which are read from their recorded backend. Use keyring when tokens must be stored in the system keyring. Use file (or leave the default) on hosts without a usable keyring. If a previous keyring login cannot be read during replacement, the CLI warns that its token could not be revoked.
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. See Environment tokens for non-production setup.

​
Logout

Revokes the current session and removes stored credentials for the active platform URL. An HTTP 401 reports an expired or revoked session without deleting local credentials. If OSMOSIS_TOKEN is still set, the CLI continues using it until you unset the variable.

​
Who Am I

Displays the currently authenticated user, token expiration, active platform URL, effective credential source, which backend (keyring or file) holds the persistent token, and whether a persistent login also exists.

​
Environment Tokens for CI/CD

Set OSMOSIS_TOKEN to authenticate non-interactive processes. When the active platform is not the default production platform, bind the token to that platform with OSMOSIS_TOKEN_PLATFORM_URL:
The CLI validates the binding before every platform request. A missing binding fails with ENV_TOKEN_PLATFORM_REQUIRED; a different normalized URL fails with ENV_TOKEN_PLATFORM_MISMATCH. Production automation against the default platform remains compatible without the binding.

​
Loading Credentials from .env

The CLI automatically loads the nearest .env file, walking upward from the current directory. Non-empty process variables win over dotenv values.
  • Pass --env-file <path> or set OSMOSIS_ENV_FILE to select a specific file.
  • Pass --platform <url> to override OSMOSIS_PLATFORM_URL for one invocation.
  • Keep OSMOSIS_TOKEN, OSMOSIS_TOKEN_PLATFORM_URL, and OSMOSIS_PLATFORM_URL together so the token cannot be sent to a platform selected independently.
  • Non-HTTPS, non-loopback platform URLs are refused unless OSMOSIS_ALLOW_INSECURE_PLATFORM_URL=1 is set.

​
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 September 14, 2026