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

# 命令參考

> CometAPI CLI 命令參考，包含 chat、models、model info、run、balance、account、stats、tokens、logs、tasks、doctor、config 與 repl。

使用 `cometapi -h` 或 `cometapi <command> -h` 來查看已安裝版本的精確參數與選項。

## 命令總覽

| Command           | Description                                   | Auth                    |
| ----------------- | --------------------------------------------- | ----------------------- |
| `chat [MESSAGE]`  | 傳送聊天訊息或啟動聊天 REPL                              | API key                 |
| `models`          | 列出並篩選模型目錄中繼資料                                 | API key                 |
| `model info <id>` | 查看單一模型的公開中繼資料                                 | API key                 |
| `run [MODEL]`     | 透過 chat、responses、anthropic 或 gemini 格式傳送單一請求 | API key                 |
| `balance`         | 顯示帳戶或目前 API key 餘額                            | API key or access token |
| `account`         | 顯示帳戶個人資料                                      | Access token            |
| `stats`           | 顯示使用統計                                        | Access token            |
| `tokens`          | 列出並搜尋 API key                                 | Access token            |
| `logs`            | 使用篩選條件瀏覽使用記錄                                  | Access token            |
| `tasks`           | 顯示非同步任務記錄                                     | Access token            |
| `init`            | 執行設定精靈                                        | None                    |
| `doctor`          | 執行診斷                                          | API key                 |
| `config`          | 管理本機設定                                        | None                    |
| `repl`            | 啟動互動式命令 shell                                 | Depends on command used |

標記為 **Access token** 的命令需要設定 `COMETAPI_ACCESS_TOKEN` 環境變數或 `access_token` 設定鍵。詳情請參閱[設定指南](/zh-Hant/libraries/cli/configuration)。

## Chat

傳送單一訊息，或啟動多輪聊天 REPL。

```bash theme={null}
cometapi chat "Explain CometAPI in one sentence."
cometapi chat "Summarize this" --model your-model-id --system "Be concise."
cometapi chat "Hello" --no-stream
cometapi chat "Hello" --json
cometapi chat
```

| Option                 | Short | Description |
| ---------------------- | ----- | ----------- |
| `--model`              | `-m`  | 要使用的模型      |
| `--system`             | `-s`  | 系統 Prompt   |
| `--temperature`        | `-t`  | 取樣溫度        |
| `--max-tokens`         |       | 回應 Token 上限 |
| `--stream/--no-stream` |       | 啟用或停用串流     |
| `--format`             | `-f`  | 輸出格式        |
| `--json`               |       | 以 JSON 輸出   |

## Models

預設會列出公開目錄中的模型。目錄輸出包含 model ID、provider、模型類型、功能、端點、定價、上下文長度，以及最大補全 Token 數。

```bash theme={null}
cometapi models
cometapi models --search gpt --limit 10
cometapi models --provider openai --type chat --limit 10
cometapi models --feature image --endpoint responses --json
cometapi models --refresh
cometapi models --source openai --search gpt
```

| Option                      | Short | Description                               |
| --------------------------- | ----- | ----------------------------------------- |
| `--search`                  | `-s`  | 依 ID、code、name、description 或 provider 篩選  |
| `--provider`                |       | 依 provider 名稱或 code 篩選                    |
| `--type`, `--modality`      |       | 依模型類型或模態篩選                                |
| `--feature`, `--capability` |       | 依功能或能力篩選                                  |
| `--endpoint`                |       | 依端點名稱、方法或路徑篩選                             |
| `--limit`                   | `-l`  | 結果數量上限                                    |
| `--source`                  |       | 使用 `catalog` 中繼資料或相容 OpenAI 的 `openai` 列表 |
| `--refresh`                 |       | 重新整理一小時的目錄快取                              |
| `--no-cache`                |       | 此命令略過目錄快取                                 |
| `--format`                  | `-f`  | 輸出格式                                      |
| `--json`                    |       | 以 JSON 輸出                                 |

目錄快取儲存在 `~/.cache/cometapi/models.json`。

## 模型資訊

檢查單一模型的公開中繼資料。此指令會先透過公開目錄解析模型，然後載入該目錄代碼的詳細中繼資料。

```bash theme={null}
cometapi model info your-model-id
cometapi model info your-model-id --json
cometapi model info your-model-id --refresh
```

| 選項           | 縮寫   | 說明              |
| ------------ | ---- | --------------- |
| `--refresh`  |      | 查詢前重新整理目錄快取     |
| `--no-cache` |      | 針對此指令略過目錄快取     |
| `--format`   | `-f` | 輸出格式            |
| `--json`     |      | 輸出原始模型詳細資訊 JSON |

表格輸出包含 provider、模型類型、功能、端點、定價、上下文長度、最大 completion token 數、文件 URL，以及概覽。

## 執行

透過選定的端點格式送出單一請求。使用 `--input-file` 傳入 JSON request body，重複使用 `-i key=value` 設定覆寫值，並使用 `-p/--prompt` 作為 prompt 捷徑。

```bash theme={null}
cometapi run your-model-id -p "Write one sentence about CometAPI."
cometapi run your-model-id --endpoint responses -p "Reply with OK only." -i max_output_tokens=32 --json
cometapi run your-model-id --endpoint anthropic -p "Reply with OK only." -i max_tokens=32
cometapi run your-model-id --endpoint gemini -p "Reply with OK only." -i generationConfig.maxOutputTokens=32
cometapi run your-model-id --endpoint responses --input-file body.json -i temperature=0.2 --json
```

| 選項             | 縮寫   | 說明                                             |
| -------------- | ---- | ---------------------------------------------- |
| `--endpoint`   | `-e` | 端點格式：`chat`、`responses`、`anthropic` 或 `gemini` |
| `--input-file` |      | JSON 物件 request body                           |
| `--input`      | `-i` | 以 `key=value` 形式提供請求輸入；可重複指定多個值                |
| `--prompt`     | `-p` | Prompt 捷徑                                      |
| `--json`       |      | 輸出原始 JSON 回應                                   |

端點對應：

| 端點          | 請求路徑                         | 驗證                                   |
| ----------- | ---------------------------- | ------------------------------------ |
| `chat`      | `POST /v1/chat/completions`  | Bearer API key                       |
| `responses` | `POST /v1/responses`         | Bearer API key                       |
| `anthropic` | `POST /v1/messages`          | `x-api-key` API key 與 Anthropic 版本標頭 |
| `gemini`    | Gemini Generate Content 模型路徑 | `x-goog-api-key` API key             |

body 合併順序為 `--input-file`、重複的 `-i key=value`、prompt 捷徑，最後是位置參數 `MODEL`。若可能，內嵌值會解析為 JSON。帶點的鍵會建立巢狀物件。

## 餘額

顯示你的 CometAPI 帳戶餘額或目前 API key 的計費檢視。

```bash theme={null}
cometapi balance
cometapi balance --source account
cometapi balance --source key
cometapi balance --json
```

| 選項         | 縮寫   | 說明                     |
| ---------- | ---- | ---------------------- |
| `--source` | `-s` | 資料來源：`account` 或 `key` |
| `--format` | `-f` | 輸出格式                   |
| `--json`   |      | 以 JSON 輸出              |

## 帳戶

顯示你的帳戶設定檔。需要 access token。

```bash theme={null}
cometapi account
cometapi account --json
```

## 統計

顯示用量統計。需要 access token。

```bash theme={null}
cometapi stats
cometapi stats --json
```

## Token

列出並搜尋 API key。需要 access token。

```bash theme={null}
cometapi tokens
cometapi tokens --search project
cometapi tokens --json
```

| 選項         | 縮寫   | 說明        |
| ---------- | ---- | --------- |
| `--search` | `-s` | 搜尋關鍵字     |
| `--page`   | `-p` | 頁碼        |
| `--limit`  | `-l` | 每頁結果數     |
| `--format` | `-f` | 輸出格式      |
| `--json`   |      | 以 JSON 輸出 |

## Logs

使用篩選條件瀏覽用量日誌。需要 access token。

```bash theme={null}
cometapi logs
cometapi logs --model your-model-id
cometapi logs --start 2026-04-01 --end 2026-04-14
cometapi logs --type consume
cometapi logs --export > usage.csv
cometapi logs --limit 50 --json
cometapi logs --request-id 20260617165550885561292gJBlzjtp
```

| Option         | Short | Description                       |
| -------------- | ----- | --------------------------------- |
| `--model`      | `-m`  | 依 model ID 篩選                     |
| `--token-name` | `-t`  | 依 API key 名稱篩選                    |
| `--type`       |       | 日誌類型                              |
| `--search`     | `-s`  | 搜尋關鍵字                             |
| `--start`      |       | 開始日期                              |
| `--end`        |       | 結束日期                              |
| `--group`      | `-g`  | 依 API key 群組篩選                    |
| `--request-id` |       | 透過 `X-Cometapi-Request-Id` 查詢單一請求 |
| `--page`       | `-p`  | 頁碼                                |
| `--limit`      | `-l`  | 每頁結果數                             |
| `--export`     |       | 將伺服器端 CSV 輸出到 stdout              |
| `--format`     | `-f`  | 輸出格式                              |
| `--json`       |       | 以 JSON 輸出                         |

`logs --request-id` 會對 operator log 端點執行一次已建立索引的查詢，且
只接受完全相符的 `request_id`。CLI 不會掃描備援日誌頁面，
因為 self-log 端點不支援套用 `request_id` 篩選。

## Tasks

顯示非同步任務日誌。需要 access token。

```bash theme={null}
cometapi tasks
cometapi tasks --platform kling
cometapi tasks --status SUCCESS
cometapi tasks --json
```

| Option       | Short | Description  |
| ------------ | ----- | ------------ |
| `--platform` | `-p`  | 依平台篩選        |
| `--task-id`  |       | 依 task ID 篩選 |
| `--status`   | `-s`  | 依狀態篩選        |
| `--action`   | `-a`  | 依動作類型篩選      |
| `--start`    |       | 開始日期         |
| `--end`      |       | 結束日期         |
| `--page`     |       | 頁碼           |
| `--limit`    | `-l`  | 每頁結果數        |
| `--format`   | `-f`  | 輸出格式         |
| `--json`     |       | 以 JSON 輸出    |

## Doctor

執行診斷以驗證設定與 API 連線能力。

```bash theme={null}
cometapi doctor
cometapi doctor --json
```

## Config

管理儲存在 `~/.config/cometapi/config.toml` 中的 CLI 設定。

```bash theme={null}
cometapi config show
cometapi config set api_key "$COMETAPI_KEY"
cometapi config set default_model your-model-id
cometapi config unset api_key
cometapi config path
```

請參閱[設定指南](/zh-Hant/libraries/cli/configuration)以查看所有可用的鍵。

## Init

執行互動式設定精靈：

```bash theme={null}
cometapi init
```

## Repl

啟動完整的互動式命令 shell：

```bash theme={null}
cometapi repl
```

## Output formats

大多數資料命令都支援 `--json` 或 `--format`：

```bash theme={null}
cometapi models --json
cometapi models --format yaml
cometapi stats --format csv
cometapi account --format markdown
```

| Format     | Description |
| ---------- | ----------- |
| `table`    | 終端機中的豐富表格   |
| `json`     | JSON 輸出     |
| `yaml`     | YAML 輸出     |
| `csv`      | 逗號分隔值       |
| `markdown` | Markdown 表格 |