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

# 安装与认证

> 安装 Osmosis CLI 并通过平台认证

## 安装

从 PyPI 安装 Osmosis CLI：

<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 或更高版本**。该 package 注册了三个等价 CLI alias：`osmosis`、`osmosis-ai` 和 `osmosis_ai`。
</Note>

验证安装：

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

### 升级

CLI 可以就地自升级。它会自动检测您的安装方式（`pip`、`pipx` 或 `uv tool`），并运行相应升级命令：

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

<Tip>
  您也可以使用自己选择的 package manager 手动升级：

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

### 版本兼容性

CLI 会在每次请求时将自身版本发送给平台，平台会据此提示何时建议或必须升级：

* **弃用警告。** 如果您安装的版本即将停止支持，CLI 会向 stderr 打印一次性的黄色 `⚠` 警告。命令仍可正常运行——您可以在方便时安排升级。
* **必须升级。** 如果您的版本低于最低支持版本，平台请求会以 `Upgrade required` 错误失败并退出命令。请运行 `osmosis upgrade`（或对应安装方式的等效命令）以继续。

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

## 认证

### Login

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

打开基于浏览器的 OAuth flow 来认证 CLI session。凭证会存储在本地，并在后续命令中复用。

| Option            | Description                                       |
| ----------------- | ------------------------------------------------- |
| `-f`, `--force`   | 强制重新登录并清除现有凭证                                     |
| `--token <TOKEN>` | 使用 personal access token 而不是浏览器 flow 认证（适合 CI/CD） |

<Tip>
  对于 CI/CD pipelines，请设置 `OSMOSIS_TOKEN` 环境变量，而不是运行 `osmosis auth login`。设置该变量后，CLI 会自动使用它，且 `login` 命令会被禁用。
</Tip>

### Logout

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

撤销当前 session 并清除本地凭证。

| Option        | Description |
| ------------- | ----------- |
| `-y`, `--yes` | 跳过确认提示      |

### Who Am I

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

显示当前已认证用户和 token 过期日期。

## Workspace Context

大多数平台命令会通过您当前所在的 workspace repository 确定 scope。如果您是首次设置 Osmosis，请先完成 [Onboarding](/zh/platform/onboarding)，再运行 workspace-scoped 命令。

如需了解 CLI 如何读取 GitHub `origin`，并将本地命令映射到平台 workspace，请参见 [Workspace Repository](/zh/cli/workspace/repository)。

## 下一步

<CardGroup cols={2}>
  <Card title="Onboarding" icon="route" href="/zh/platform/onboarding">
    设置 workspace repository 和本地 CLI context。
  </Card>

  <Card title="Command Reference" icon="rectangle-list" href="/zh/cli/command-reference">
    每个 CLI 命令及其选项的完整参考。
  </Card>
</CardGroup>