> ## 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.

# Command reference

> Reference for CometAPI CLI commands, including chat, models, model info, run, balance, account, stats, tokens, logs, tasks, doctor, config, and repl.

Use `cometapi -h` or `cometapi <command> -h` to inspect the exact arguments and options for the installed version.

## Commands overview

| Command           | Description                                                            | Auth                    |
| ----------------- | ---------------------------------------------------------------------- | ----------------------- |
| `chat [MESSAGE]`  | Send a chat message or start the chat REPL                             | API key                 |
| `models`          | List and filter model catalog metadata                                 | API key                 |
| `model info <id>` | Inspect one model's public metadata                                    | API key                 |
| `run [MODEL]`     | Send one request through chat, responses, anthropic, or gemini formats | API key                 |
| `balance`         | Show account or current API key balance                                | API key or access token |
| `account`         | Show account profile                                                   | Access token            |
| `stats`           | Show usage statistics                                                  | Access token            |
| `tokens`          | List and search API keys                                               | Access token            |
| `logs`            | Browse usage logs with filters                                         | Access token            |
| `tasks`           | Show async task logs                                                   | Access token            |
| `init`            | Run the setup wizard                                                   | None                    |
| `doctor`          | Run diagnostics                                                        | API key                 |
| `config`          | Manage local configuration                                             | None                    |
| `repl`            | Start an interactive command shell                                     | Depends on command used |

Commands marked **Access token** require the `COMETAPI_ACCESS_TOKEN` environment variable or the `access_token` config key. See the [configuration guide](/libraries/cli/configuration) for details.

## Chat

Send a single message or start the multi-turn 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`  | Model to use                |
| `--system`             | `-s`  | System prompt               |
| `--temperature`        | `-t`  | Sampling temperature        |
| `--max-tokens`         |       | Maximum response tokens     |
| `--stream/--no-stream` |       | Enable or disable streaming |
| `--format`             | `-f`  | Output format               |
| `--json`               |       | Output as JSON              |

## Models

List models from the public catalog by default. Catalog output includes model ID, provider, model type, features, endpoints, pricing, context length, and maximum completion tokens.

```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`  | Filter by ID, code, name, description, or provider           |
| `--provider`                |       | Filter by provider name or code                              |
| `--type`, `--modality`      |       | Filter by model type or modality                             |
| `--feature`, `--capability` |       | Filter by feature or capability                              |
| `--endpoint`                |       | Filter by endpoint name, method, or path                     |
| `--limit`                   | `-l`  | Maximum number of results                                    |
| `--source`                  |       | Use `catalog` metadata or OpenAI-compatible `openai` listing |
| `--refresh`                 |       | Refresh the one-hour catalog cache                           |
| `--no-cache`                |       | Bypass the catalog cache for this command                    |
| `--format`                  | `-f`  | Output format                                                |
| `--json`                    |       | Output as JSON                                               |

The catalog cache is stored at `~/.cache/cometapi/models.json`.

## Model info

Inspect public metadata for one model. The command resolves the model through the public catalog, then loads detail metadata for the catalog code.

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

| Option       | Short | Description                               |
| ------------ | ----- | ----------------------------------------- |
| `--refresh`  |       | Refresh the catalog cache before lookup   |
| `--no-cache` |       | Bypass the catalog cache for this command |
| `--format`   | `-f`  | Output format                             |
| `--json`     |       | Output raw model detail JSON              |

Table output includes provider, model type, features, endpoints, pricing, context length, maximum completion tokens, documentation URL, and overview.

## Run

Send one request through a selected endpoint format. Use `--input-file` for a JSON body, repeated `-i key=value` values for overrides, and `-p/--prompt` for a prompt shortcut.

```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
```

| Option         | Short | Description                                                    |
| -------------- | ----- | -------------------------------------------------------------- |
| `--endpoint`   | `-e`  | Endpoint format: `chat`, `responses`, `anthropic`, or `gemini` |
| `--input-file` |       | JSON object request body                                       |
| `--input`      | `-i`  | Request input as `key=value`; repeat for multiple values       |
| `--prompt`     | `-p`  | Prompt shortcut                                                |
| `--json`       |       | Output raw JSON response                                       |

Endpoint mapping:

| Endpoint    | Request path                       | Auth                                             |
| ----------- | ---------------------------------- | ------------------------------------------------ |
| `chat`      | `POST /v1/chat/completions`        | Bearer API key                                   |
| `responses` | `POST /v1/responses`               | Bearer API key                                   |
| `anthropic` | `POST /v1/messages`                | `x-api-key` API key and Anthropic version header |
| `gemini`    | Gemini Generate Content model path | `x-goog-api-key` API key                         |

Body merge order is `--input-file`, repeated `-i key=value`, prompt shortcut, then positional `MODEL`. Inline values parse JSON when possible. Dotted keys create nested objects.

## Balance

Show your CometAPI account balance or current API key billing view.

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

| Option     | Short | Description                     |
| ---------- | ----- | ------------------------------- |
| `--source` | `-s`  | Data source: `account` or `key` |
| `--format` | `-f`  | Output format                   |
| `--json`   |       | Output as JSON                  |

## Account

Show your account profile. Requires an access token.

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

## Stats

Show usage statistics. Requires an access token.

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

## Tokens

List and search API keys. Requires an access token.

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

| Option     | Short | Description      |
| ---------- | ----- | ---------------- |
| `--search` | `-s`  | Search keyword   |
| `--page`   | `-p`  | Page number      |
| `--limit`  | `-l`  | Results per page |
| `--format` | `-f`  | Output format    |
| `--json`   |       | Output as JSON   |

## Logs

Browse usage logs with filters. Requires an 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`  | Filter by model ID                             |
| `--token-name` | `-t`  | Filter by API key name                         |
| `--type`       |       | Log type                                       |
| `--search`     | `-s`  | Search keyword                                 |
| `--start`      |       | Start date                                     |
| `--end`        |       | End date                                       |
| `--group`      | `-g`  | Filter by API key group                        |
| `--request-id` |       | Look up one request by `X-Cometapi-Request-Id` |
| `--page`       | `-p`  | Page number                                    |
| `--limit`      | `-l`  | Results per page                               |
| `--export`     |       | Output server-side CSV to stdout               |
| `--format`     | `-f`  | Output format                                  |
| `--json`       |       | Output as JSON                                 |

`logs --request-id` performs one indexed lookup against the operator log endpoint and
accepts only an exact `request_id` match. The CLI does not scan fallback log pages,
because the self-log endpoint does not apply `request_id` filtering.

## Tasks

Show async task logs. Requires an access token.

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

| Option       | Short | Description           |
| ------------ | ----- | --------------------- |
| `--platform` | `-p`  | Filter by platform    |
| `--task-id`  |       | Filter by task ID     |
| `--status`   | `-s`  | Filter by status      |
| `--action`   | `-a`  | Filter by action type |
| `--start`    |       | Start date            |
| `--end`      |       | End date              |
| `--page`     |       | Page number           |
| `--limit`    | `-l`  | Results per page      |
| `--format`   | `-f`  | Output format         |
| `--json`     |       | Output as JSON        |

## Doctor

Run diagnostics to verify configuration and API connectivity.

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

## Config

Manage CLI configuration stored in `~/.config/cometapi/config.toml`.

```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
```

See the [configuration guide](/libraries/cli/configuration) for all available keys.

## Init

Run the interactive setup wizard:

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

## Repl

Start a full interactive command shell:

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

## Output formats

Most data commands support `--json` or `--format`:

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

| Format     | Description                |
| ---------- | -------------------------- |
| `table`    | Rich table in the terminal |
| `json`     | JSON output                |
| `yaml`     | YAML output                |
| `csv`      | Comma-separated values     |
| `markdown` | Markdown table             |