Osmosis CLI 安装与认证

安装

从 PyPI 安装 Osmosis CLI：

pip install "osmosis-ai>=0.3.4,<0.4"

pipx install "osmosis-ai>=0.3.4,<0.4"

uv tool install "osmosis-ai>=0.3.4,<0.4"

需要 Python 3.12 或更高版本，并支持 Python 3.12、3.13 和 3.14。该 package 注册了三个等价 CLI alias：osmosis、osmosis-ai 和 osmosis_ai。

验证安装：

osmosis --version

同一个 package 也提供 Python SDK。有关 rollout dependencies、可选 extras 和 SDK 验证，请参见 SDK 安装。

升级

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

osmosis upgrade

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

pip install --upgrade osmosis-ai

pipx upgrade osmosis-ai

uv tool upgrade osmosis-ai

版本兼容性

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

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

osmosis upgrade

认证

打开基于浏览器的 OAuth flow 来认证 CLI session。CLI 优先使用 operating-system keyring 存储凭证，并以 active platform URL 为 key，因此登录可跨 working directories、virtual environments 和 uv run 复用。再次运行 auth login 会安全替换已存登录；该命令不再接受 --force。

选项	说明
`--token <TOKEN>`	使用 personal access token 而不是浏览器 flow 认证（适合 CI/CD）

凭证存储 Backend

默认情况下（OSMOSIS_TOKEN_STORE=auto），CLI 会尝试将 token 保存到 operating-system keyring。如果 keyring 不可用，则回退到 ~/.config/osmosis/credentials.json 并打印 KEYRING_UNAVAILABLE 警告。该文件通过原子写入方式保存，仅授予文件所有者读写权限（0700 目录下的 0600 文件）。运行 osmosis auth whoami 可查看有效的凭证来源以及持久登录所用的 backend。设置 OSMOSIS_TOKEN_STORE 可选择新登录的存储位置：

值	行为
`auto`（默认）	优先使用 keyring；无法写入时回退到凭证文件
`keyring`	强制使用 keyring 存储；访问或保存失败时以 `KEYRING_UNAVAILABLE` 失败，不回退到文件
`file`	将新登录保存到 `~/.config/osmosis/credentials.json`

任何其他值都会以 VALIDATION 失败。此设置只决定新登录的存储位置，不会迁移已有凭证；已有凭证仍从记录的 backend 读取。需要将 token 存储在系统 keyring 时使用 keyring。没有可用 keyring 的主机可使用 file 或保留默认值。如果替换登录时无法读取先前的 keyring 登录，CLI 会警告其 token 未能撤销。

# 无 keyring 守护进程的 headless Linux 主机
osmosis auth login
# ⚠ KEYRING_UNAVAILABLE：token 已保存到 ~/.config/osmosis/credentials.json

# 强制使用 keyring 存储，不回退到文件
OSMOSIS_TOKEN_STORE=keyring osmosis auth login

对于 CI/CD pipelines，请设置 OSMOSIS_TOKEN 环境变量，而不是运行 osmosis auth login。设置该变量后，CLI 会自动使用它，且 login 命令会被禁用。Non-production 设置参见 Environment token。

退出登录

osmosis auth logout

撤销当前 session，并删除 active platform URL 对应的已存凭证。HTTP 401 只会报告 session 已过期或被撤销，不会删除本地凭证。如果环境中仍设置了 OSMOSIS_TOKEN，CLI 会继续使用它，直到您 unset 该变量。

选项	说明
`-y`, `--yes`	跳过确认提示

查看当前身份

osmosis auth whoami

显示当前已认证用户、token 过期时间、active platform URL、effective credential source、持久 token 所在的 backend（keyring 或 file），以及是否还存在持久登录。

用于 CI/CD 的 Environment token

设置 OSMOSIS_TOKEN 可认证非交互式 process。当 active platform 不是默认 production platform 时，还必须用 OSMOSIS_TOKEN_PLATFORM_URL 将 token 绑定到该 platform：

export OSMOSIS_TOKEN="<token>"
export OSMOSIS_PLATFORM_URL="<non-production-platform-url>"
export OSMOSIS_TOKEN_PLATFORM_URL="$OSMOSIS_PLATFORM_URL"

CLI 会在每次 platform request 之前校验 binding。Binding 缺失时以 ENV_TOKEN_PLATFORM_REQUIRED 失败；normalized URL 不同则以 ENV_TOKEN_PLATFORM_MISMATCH 失败。访问默认 platform 的现有 production automation 不需要显式 binding。

从 `.env` 加载凭证

CLI 会从当前目录向上查找并自动加载最近的 .env 文件。非空 process variables 优先于 dotenv 值。

传入 --env-file <path> 或设置 OSMOSIS_ENV_FILE 可指定文件。
传入 --platform <url> 可仅为一次 invocation 覆盖 OSMOSIS_PLATFORM_URL。
将 OSMOSIS_TOKEN、OSMOSIS_TOKEN_PLATFORM_URL 和 OSMOSIS_PLATFORM_URL 放在一起，避免 token 被发送到独立选择的 platform。
非 HTTPS、非 loopback 的 platform URL 会被拒绝，除非设置 OSMOSIS_ALLOW_INSECURE_PLATFORM_URL=1。

Workspace 上下文

大多数平台命令会通过您当前所在的 workspace repository 确定 scope。如果您是首次设置 Osmosis，请先完成 Onboarding，再运行 workspace-scoped 命令。如需了解 CLI 如何读取 GitHub origin，并将本地命令映射到平台 workspace，请参见 Workspace Repository。

开始使用

运行

工作区

参考

Osmosis CLI 安装与认证

安装

升级

版本兼容性

认证

登录

凭证存储 Backend

退出登录

查看当前身份

用于 CI/CD 的 Environment token

从 `.env` 加载凭证

Workspace 上下文

下一步

入门引导

命令参考

​安装

​升级

​版本兼容性

​认证

​登录

​凭证存储 Backend

​退出登录

​查看当前身份

​用于 CI/CD 的 Environment token

​从 .env 加载凭证

​Workspace 上下文

​下一步

入门引导

命令参考

安装

升级

版本兼容性

认证

登录

凭证存储 Backend

退出登录

查看当前身份

用于 CI/CD 的 Environment token

从 `.env` 加载凭证

Workspace 上下文

下一步