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

# CLI

> 登入一次，就能在終端生成圖片、影片與聲音。

`blon` 指令以你的 Blon 帳號執行並使用帳號點數，[Skills](https://docs.blon.ai/zh-TW/how-to/skills.md) 也是透過它執行。

## 安裝

> [!NOTE]
>
> `@blon/cli` 尚未發行到 npm，以下指令在第一個版本發行後即可使用。

```bash theme={null}
npm i -g @blon/cli
# 或不安裝直接執行
npx @blon/cli --help
```

需要 Node.js 22 以上。

## 登入

```bash theme={null}
blon auth login
blon auth status
blon auth logout
```

`blon auth login` 使用裝置授權流程：印出網址與代碼，並在瀏覽器開啟核准頁，以登入中的 Blon 帳號核准即可。在 SSH 或容器中不會開啟瀏覽器，請在任何裝置上開啟印出的網址。

登入憑證存在 `~/.config/blon/credentials.json`（權限 `0600`），可用 `BLON_CONFIG_DIR` 改放其他位置。`blon whoami` 顯示帳號、站台、工作區與餘額。

## 第一個生成

```bash theme={null}
blon models list
blon models get nano-banana-2-lite
blon generate nano-banana-2-lite --prompt "A ceramic teapot on a linen table" --wait --out ./out
```

模型的每個輸入就是一個旗標：`--<inputId> <value>`，用 `blon models get <id>` 查看。list 型輸入用逗號分隔或重複旗標；負數寫成 `--seed=-1`。

## 媒體輸入

媒體旗標可給本機檔案路徑、`https://` 網址或 asset id。本機檔案會自動上傳（圖片上限 20,000,000 bytes，其他檔案 52,428,800 bytes）。

```bash theme={null}
# 本機檔案（自動上傳）
blon generate seedance-2.0 --prompt "Slow push-in" --firstFrame ./frame.png --wait --out ./out
# https 網址
blon generate seedance-2.0 --prompt "Slow push-in" --firstFrame https://example.com/frame.png --wait
# asset id
blon generate seedance-2.0 --prompt "Slow push-in" --firstFrame <asset-id> --wait
```

## 音色輸入

音色旗標給模型的預設音色 id（`blon models get <id>` 會列出可用的），或用 `workspace:<voiceId>` 指定工作區音色。

```bash theme={null}
blon generate minimax-speech-2.8-hd --text "Welcome to Blon." --voice Wise_Woman --wait
```

## 指令

| 指令 | 用途 |
| - | - |
| `blon auth login` / `status` / `logout` | 登入、查看登入帳號、登出 |
| `blon whoami` | 帳號、站台、工作區與餘額 |
| `blon balance` | 只看餘額 |
| `blon models list` / `models get <id>` | 模型與其輸入 |
| `blon estimate <model> [--<input> <value>]…` | 估價，不提交 |
| `blon generate <model> [--<input> <value>]…` | 提交工作 |
| `blon jobs list` / `get <id>` / `wait <id>` / `cancel <id>` | 管理工作 |
| `blon assets list` / `assets download <id>` | 工作區的素材 |
| `blon workflows get <revisionId>` / `workflows run <revisionId>` | [工作流](https://docs.blon.ai/zh-TW/how-to/workflows.md) |
| `blon usage [--timeframe <t>] [--start <iso>] [--end <iso>]` | 用量報表 |

`generate` 的旗標：

| 旗標 | 說明 |
| - | - |
| `--wait` | 輪詢到工作結束 |
| `--timeout <duration>` | `--wait` 的等待上限，例如 `90s`、`10m`、`1h`，預設 `10m` |
| `--out <dir>` | 把產物下載為 `<jobId>-<n>.<ext>` |
| `--idempotency-key <key>` | 重送時沿用同一把鍵；未指定時隨機產生 |
| `--webhook-url <url>` | 工作結束時送出 [webhook](https://docs.blon.ai/zh-TW/how-to/webhooks.md) |

等待中斷時，用 `blon jobs wait <id>` 接著等，不要重新提交。

全域旗標：`--json`、`--workspace <slug>`、`--base-url <url>`、`--help`、`--version`。

## JSON 輸出

加上 `--json` 時，stdout 只有回應 JSON，進度都在 stderr；搭配 `--wait` 就是整筆完成的工作。

```bash theme={null}
blon generate nano-banana-2-lite --prompt "A ceramic teapot" --wait --json
```

## 離開碼

| 離開碼 | 說明 |
| - | - |
| `0` | 成功 |
| `1` | 用法錯誤、未登入、401／403 或網路錯誤 |
| `2` | 工作失敗、已取消或等待逾時 |
| `3` | 餘額不足 |

## 環境變數

| 變數 | 說明 |
| - | - |
| `BLON_API_KEY` | `blon_api_` 金鑰，優先於已儲存的登入 |
| `BLON_BASE_URL` | 連線的站台，預設 `https://blon.ai`；`--base-url` 優先 |
| `BLON_CONFIG_DIR` | 登入憑證的存放位置，預設 `~/.config/blon` |

## CI

無人值守時設定 `BLON_API_KEY`，不需要 `blon auth login`。此時 CLI 花的是金鑰所屬工作區的餘額。

```bash theme={null}
export BLON_API_KEY=blon_api_...
blon generate nano-banana-2-lite --prompt "A ceramic teapot" --wait --json
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.