> ## 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](https://apidoc.cometapi.com/developer-tools/cli/configuration.md) 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](https://apidoc.cometapi.com/developer-tools/cli/configuration.md) 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 |


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