> ## 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 & Authentication

> Install the Osmosis CLI and authenticate with the platform

## Installation

Install the Osmosis CLI from PyPI:

<CodeGroup>
  ```bash pip theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
  pip install osmosis-ai
  ```

  ```bash pipx theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
  pipx install osmosis-ai
  ```

  ```bash uv tool theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
  uv tool install osmosis-ai
  ```
</CodeGroup>

<Note>
  Python **3.12 or later** is required. The package registers three equivalent CLI aliases: `osmosis`, `osmosis-ai`, and `osmosis_ai`.
</Note>

Verify the installation:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis upgrade
```

<Tip>
  You can also upgrade manually with your package manager of choice:

  <CodeGroup>
    ```bash pip theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
    pip install --upgrade osmosis-ai
    ```

    ```bash pipx theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
    pipx upgrade osmosis-ai
    ```

    ```bash uv tool theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
    uv tool upgrade osmosis-ai
    ```
  </CodeGroup>
</Tip>

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis upgrade
```

## Authentication

### Login

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis auth login
```

Opens a browser-based OAuth flow to authenticate your CLI session. Credentials are stored locally and reused for subsequent commands.

| Option            | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| `-f`, `--force`   | Force re-login, clearing existing credentials                                        |
| `--token <TOKEN>` | Authenticate with a personal access token instead of browser flow (useful for CI/CD) |

<Tip>
  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.
</Tip>

### Logout

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis auth logout
```

Revokes the current session and clears local credentials.

| Option        | Description              |
| ------------- | ------------------------ |
| `-y`, `--yes` | Skip confirmation prompt |

### Who Am I

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
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](/platform/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](/cli/workspace/repository).

## Next Steps

<CardGroup cols={2}>
  <Card title="Onboarding" icon="route" href="/platform/onboarding">
    Set up a workspace repository and local CLI context.
  </Card>

  <Card title="Command Reference" icon="rectangle-list" href="/cli/command-reference">
    Full reference for every CLI command and its options.
  </Card>
</CardGroup>