> ## 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`）？請見[透過介面取得帳戶資訊](/zh-Hant/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](/zh-Hant/api/CliEndpoints/get-self) · [舊版 Python 腳本](/zh-Hant/api/Cli) · [AIHubMix 控制台](https://console.aihubmix.com)*

***

更新時間：2026-06-22