> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AIHubMix CLI（命令行工具）

> AIHubMix CLI 是 AIHubMix 官方命令行工具，单一二进制、零依赖，在终端即可查询账户余额、管理 API Key、查看可用模型，并对脚本与 AI Agent 友好。

**AIHubMix CLI** 是 AIHubMix 官方命令行工具（可执行文件 `aihubmix`）。安装后，你无需打开网页控制台，就能在终端查询账户余额、管理 API Key、查看可用模型。它是单一二进制文件，**无需安装 Python、Node 或 Go**，一条命令即可装好；所有命令都支持 JSON 输出，可直接接入脚本、CI 与 AI Agent（如 Claude Code）。

**它能做什么：**

* **查余额**：实时查询账户余额与已用额度
* **管 Key**：创建、查看、搜索、修改、删除 API Key
* **看模型**：列出当前令牌可用的模型
* **可脚本化**：JSON 输出 + 稳定退出码，天然适配自动化与 AI Agent

<Info>
  **两种凭证别搞混**：CLI 用「系统访问令牌」（Manage Key，格式 `fd***`）登录，在控制台 [console.aihubmix.com/setting](https://console.aihubmix.com/setting) 点「生成系统访问令牌」获取。它用于**管理账户**，和你调用模型用的 API Key（`sk-***`）不是同一个。
</Info>

<Tip>
  在找旧版 Python 脚本（`aihubmix_cli.py`）？请见[通过接口获取账户信息](/cn/api/Cli)。本页是它的新一代替代品，更简单、更快。
</Tip>

## 安装

### 一键安装（推荐）

复制对应系统的命令，粘贴到终端运行，即可下载二进制并自动加入 `PATH`：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  curl -fsSL https://raw.githubusercontent.com/AIhubmix/platfrom-cli/main/install.sh | sh
  ```

  ```powershell Windows PowerShell theme={null}
  irm https://raw.githubusercontent.com/AIhubmix/platfrom-cli/main/install.ps1 | iex
  ```
</CodeGroup>

装好后**重开一个终端**，运行 `aihubmix login` 即可开始使用。

<Info>
  也可到 [Releases](https://github.com/AIhubmix/platfrom-cli/releases) 手动下载对应平台的二进制（Windows 为 `aihubmix_windows_amd64.exe`），放入 `PATH` 目录；类 Unix 系统需 `chmod +x`。
</Info>

需要时，可用环境变量调整安装行为：

| 变量                 | 说明                 | 默认                                                                           |
| ------------------ | ------------------ | ---------------------------------------------------------------------------- |
| `AIHUBMIX_VERSION` | 安装指定版本（如 `v0.2.0`） | `latest`                                                                     |
| `AIHUBMIX_BIN_DIR` | 自定义安装目录            | Unix：`/usr/local/bin` 或 `~/.local/bin`；Windows：`%LOCALAPPDATA%\aihubmix\bin` |

## 快速开始

登录后即可使用全部命令：

```bash theme={null}
# 1. 登录：自动打开浏览器到令牌生成页，粘贴 Manage Key（输入不回显）
aihubmix login

# 2. 查看当前身份与余额
aihubmix whoami

# 3. 查看完整账户信息
aihubmix me

# 4. 列出你的 API Key
aihubmix keys list
```

## 命令参考

| 命令                               | 作用                |
| -------------------------------- | ----------------- |
| `aihubmix login`                 | 登录（粘贴 Manage Key） |
| `aihubmix logout`                | 登出，清除本地凭证         |
| `aihubmix whoami`                | 查看当前登录身份与余额       |
| `aihubmix me`                    | 查看完整账户信息与余额       |
| `aihubmix models list`           | 查看当前可用模型          |
| `aihubmix keys list [--num N]`   | 列出 API Key        |
| `aihubmix keys search <关键字>`     | 按关键字搜索 Key        |
| `aihubmix keys get <id>`         | 查看指定 Key 详情       |
| `aihubmix keys create [参数]`      | 创建新 Key           |
| `aihubmix keys update <id> [参数]` | 修改 Key            |
| `aihubmix keys delete <id>`      | 删除 Key            |

<Tip>
  任意命令加 `--help` 可查看完整参数，例如 `aihubmix keys create --help`。
</Tip>

## 常用操作

### 管理 API Key

```bash theme={null}
# 创建一个 $10 限额、仅限指定模型的 Key
aihubmix keys create -n prod-key -q 10 -m "gpt-4o,claude-3.5-sonnet"

# 创建一个不限额度、永不过期的 Key
aihubmix keys create -n ci-key -u

# 重命名 Key（其余设置不变）
aihubmix keys update 123 -n new-name

# 停用某个 Key
aihubmix keys update 123 --status 0

# 删除 Key
aihubmix keys delete 123
```

其中 `-q 10` 表示该 Key 限额 \$10，`-u` 表示不限额度。删除默认会要求确认，CI 场景可加 `--yes` 跳过。

### 在脚本 / AI Agent 中使用

CLI 对自动化非常友好，可被 CI、脚本或 AI Agent（如 Claude Code）直接驱动：

* **免登录**：用环境变量 `AIHUBMIX_TOKEN` 或 `--token` 传入 Manage Key，跳过交互式登录（优先级：`--token` > `AIHUBMIX_TOKEN` > 配置文件）。
* **JSON 输出**：任意命令加 `--json`（`-j`），正常结果走 stdout、错误走 stderr，方便 `jq` 解析。
* **稳定退出码**：脚本可据此判断成败。

```bash theme={null}
# 用环境变量驱动，提取所有 Key 名称
AIHUBMIX_TOKEN=fd*** aihubmix keys list --json | jq '.data[].name'

# 查询余额
AIHUBMIX_TOKEN=fd*** aihubmix whoami --json | jq -r '.balance'
```

退出码含义：

| 退出码 | 含义                   |
| --- | -------------------- |
| `0` | 成功                   |
| `1` | 通用错误（参数错误、业务失败等）     |
| `2` | 鉴权失败（未登录 / Token 无效） |
| `3` | 网络 / 连接错误            |

## 全局参数

以下参数对所有命令生效：

| 参数                 | 简写   | 说明                                    |
| ------------------ | ---- | ------------------------------------- |
| `--token <token>`  | `-t` | 直接传入 Manage Key（CI / 脚本场景）            |
| `--json`           | `-j` | 以 JSON 格式输出                           |
| `--base-url <url>` | `-b` | 自定义 API 地址（默认 `https://aihubmix.com`） |
| `--no-color`       |      | 关闭彩色输出                                |
| `--config <path>`  |      | 指定配置文件路径                              |
| `--version`        |      | 查看版本                                  |

## 配置文件

登录信息保存在 `~/.aihubmix/config.json`（Windows 为 `%USERPROFILE%\.aihubmix\config.json`），权限被收紧为**仅当前用户可读写**。登录时 Manage Key 不回显、不写入日志。

<Warning>
  请勿将 Manage Key 提交到代码仓库或分享给他人。一旦泄露，请到控制台重新生成，旧令牌会立即失效。
</Warning>

## 常见问题

**需要安装 Python / Node / Go 吗？**

不需要。CLI 是单一二进制文件，下载即用。

**Manage Key 和 API Key 有什么区别？**

Manage Key（`fd***`）用于管理账户（查余额、管 Key），由 CLI 使用；API Key（`sk-***`）用于调用模型。两者在控制台不同位置生成，不能混用。

**支持 Windows 吗？**

支持。Windows、macOS、Linux 均提供原生二进制。

**如何在 CI / 脚本中免交互使用？**

通过环境变量 `AIHUBMIX_TOKEN` 传入 Manage Key，再配合 `--json` 与退出码即可，无需运行 `aihubmix login`。

**忘记或泄露了 Manage Key 怎么办？**

到 [console.aihubmix.com/setting](https://console.aihubmix.com/setting) 重新生成，旧令牌即失效。

***

*相关文档：[平台 API · CliEndpoints](/cn/api/CliEndpoints/get-self) · [旧版 Python 脚本](/cn/api/Cli) · [AIHubMix 控制台](https://console.aihubmix.com)*

***

更新时间：2026-06-22