> ## 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` 查看已安装版本的确切参数和选项。

## Commands overview

| 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 或 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                                 | 取决于所使用的命令              |

标记为 **Access token** 的命令需要 `COMETAPI_ACCESS_TOKEN` 环境变量或 `access_token` 配置键。详情请参阅[配置指南](/zh-Hans/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 和概览。

## 运行

通过选定的端点格式发送一次请求。对 JSON 请求体使用 `--input-file`，使用可重复的 `-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 对象请求体                                     |
| `--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            |

请求体合并顺序为 `--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 输出 |

## 日志

使用筛选条件浏览使用日志。需要访问令牌。

```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 endpoint 执行一次索引查找，
并且只接受精确的 `request_id` 匹配。CLI 不会扫描备用日志分页，
因为 self-log endpoint 不支持应用 `request_id` 过滤。

## 任务

显示异步任务日志。需要访问令牌。

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

| Option       | Short | Description |
| ------------ | ----- | ----------- |
| `--platform` | `-p`  | 按平台筛选       |
| `--task-id`  |       | 按任务 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/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-Hans/libraries/cli/configuration)。

## Init

运行交互式设置向导：

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

## Repl

启动完整的交互式命令 shell：

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

## 输出格式

大多数数据命令都支持 `--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 表格 |