CometAPI CLI

Official command-line interface for CometAPI, a multi-model AI gateway for GPT, Claude, Gemini, image, audio, and video models.

The PyPI package page is the public homepage for installation and release metadata. The public documentation is available at CometAPI CLI docs.

Features

• Chat with CometAPI models from the terminal, with streaming and an interactive REPL
• Browse the public model catalog with provider, modality, endpoint, capability, context, and pricing metadata
• Inspect one model with cometapi model info <id>
• Send one request through OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, or Gemini Generate Content with cometapi run
• Check balance, account data, usage stats, API keys, logs, async task history, and operator-only ops data
• Output tables, JSON, YAML, CSV, or Markdown for terminal use and automation
• Store local configuration in ~/.config/cometapi/config.toml

Installation

The CLI requires Python 3.10 or later.

pip install cometapi-cli

You can also install it in an isolated tool environment:

pipx install cometapi-cli
uv tool install cometapi-cli

Create an API key in the CometAPI console. Account-management commands can also use an optional access token.

Quick start

Run the setup wizard:

cometapi init

Or configure credentials with environment variables:

export COMETAPI_KEY="your-api-key"
export COMETAPI_ACCESS_TOKEN="your-access-token"  # optional, for account/log/task/ops commands

Verify the installation and available commands:

cometapi --version
cometapi -h
cometapi doctor

Send a chat message:

cometapi chat "Explain quantum computing in one sentence"

Search the model catalog:

cometapi models --search gpt --limit 10

Inspect one model:

cometapi model info your-model-id

Run a one-off request through the default chat endpoint:

cometapi run your-model-id -p "Reply with OK only."

Command reference

Use -h on the root command or any subcommand to see the exact options for the installed version:

cometapi -h
cometapi models -h
cometapi model info -h
cometapi run -h
cometapi ops -h

Logs

Use cometapi logs to inspect recent usage, export CSV, or look up one request by the X-Cometapi-Request-Id response header.

cometapi logs --limit 20
cometapi logs --type consume --start 2026-06-01 --json
cometapi logs --request-id 20260617165550885561292gJBlzjtp

logs --request-id first performs an indexed lookup against the operator log endpoint and accepts only an exact request_id match. If that lookup is not available to the current access token, the CLI falls back to one bounded recent self-log page scan and still requires an exact match.

Ops

cometapi ops provides read-only operator/admin queries for internal support workflows. It uses a Console access token and does not require a CometAPI API key.

export COMETAPI_ACCESS_TOKEN="your-access-token"

cometapi ops logs --user-id 55997 --start 2026-07-01 --end 2026-07-03 --json
cometapi ops usage --user-id 55997 --start 2026-07-01 --end 2026-07-03
cometapi ops topups --email customer@example.com --limit 20 --json

Available subcommands:

• ops logs — query cross-user usage logs by user, username, model, token name, type, request ID, and time range.
• ops usage — summarize cross-user usage from the backend /api/log/stat aggregation endpoint.
• ops topups — query top-up orders by user ID, exact email, CometAPI order number, Stripe payment intent ID, keyword, and time range.

Normal user accounts are rejected with insufficient_role. No ops command performs write actions such as refunds, quota changes, account disabling, or payment repair.

Models

cometapi models uses the public model catalog by default and displays richer metadata than /v1/models.

# Search by keyword
cometapi models --search gpt --limit 10

# Filter by provider, modality, capability, or endpoint
cometapi models --provider openai --type chat --limit 10
cometapi models --feature image --endpoint responses --json

# Refresh the one-hour local cache
cometapi models --refresh

# Use the OpenAI-compatible /v1/models source
cometapi models --source openai --search gpt

Catalog rows include:

• id
• provider
• model_type
• features
• endpoints
• pricing
• context_length
• max_completion_tokens

The catalog cache is stored at ~/.cache/cometapi/models.json. Use --refresh to replace stale cache data or --no-cache to bypass the cache for one command.

Model info

Use cometapi model info <id> when you need the detail page metadata for one model.

# Human-readable table
cometapi model info your-model-id

# Raw model detail JSON
cometapi model info your-model-id --json

# Refresh catalog metadata before resolving the model
cometapi model info your-model-id --refresh

The command resolves the public catalog entry first, then loads detail metadata from the model detail API. It supports slash-style model IDs and dotted IDs.

Run

cometapi run is a unified request entrypoint for CometAPI's multi-protocol gateway. It accepts an optional positional model, a JSON request body, repeated inline inputs, and a prompt shortcut.

# OpenAI Chat Completions format (default)
cometapi run your-model-id -p "Write one sentence about CometAPI."

# OpenAI Responses format
cometapi run your-model-id --endpoint responses -p "Reply with OK only." -i max_output_tokens=32 --json

# Anthropic Messages format
cometapi run your-model-id --endpoint anthropic -p "Reply with OK only." -i max_tokens=32

# Gemini Generate Content format
cometapi run your-model-id --endpoint gemini -p "Reply with OK only." -i generationConfig.maxOutputTokens=32

Build a request from a JSON file and override fields inline:

cometapi run your-model-id \
  --endpoint responses \
  --input-file body.json \
  -i temperature=0.2 \
  -i metadata.source='"cli"' \
  --json

Input precedence is:

1. --input-file JSON object
2. Repeated -i key=value values
3. -p/--prompt convenience body
4. Positional MODEL, which overrides body.model

-i key=value parses JSON values when possible, so numbers, booleans, null, objects, and arrays can be passed without string coercion. Dotted keys create nested JSON objects.

Output formats

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

cometapi models --json
cometapi models --format yaml
cometapi stats --format csv
cometapi account --format markdown

Set a persistent default format:

cometapi config set output_format json

Configuration

Config file: ~/.config/cometapi/config.toml

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

Configuration priority: CLI flags > config file > environment variables > defaults.

Chat REPL

Run cometapi chat without a message to start a multi-turn chat session.

cometapi chat

Available slash commands:

Security

• API keys and access tokens are never displayed in full by CLI diagnostics.
• Config files are stored with restrictive permissions (0600).
• Keep credentials out of source control and shell history.
• You are responsible for usage and charges incurred with your API keys.

Troubleshooting

License

MIT