cometapi-cli 0.3.0

CometAPI CLI — official command-line interface for the CometAPI AI gateway

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, and async task history
• 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 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

Command	Description	Credential
chat [MESSAGE]	Send a chat message or start the chat REPL	API key
models	List and filter public model catalog metadata	API key
model info <id>	Show provider, endpoint, capability, context, pricing, and docs metadata for one model	API key
run [MODEL]	Send one request through chat, responses, anthropic, or gemini endpoint 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 and export CSV	Access token
tasks	Browse async task logs	Access token
init	Run the interactive setup wizard	None
doctor	Check configuration and connectivity	API key
repl	Start an interactive command shell	Depends on command used
config	Show, set, unset, or locate local configuration	None

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

Key	Env variable	Description
api_key	COMETAPI_KEY	API key for model and balance commands
access_token	COMETAPI_ACCESS_TOKEN	Access token for account, stats, token, log, and task commands
base_url	COMETAPI_BASE_URL	API base URL
default_model	COMETAPI_DEFAULT_MODEL	Default model for chat and run
output_format	-	Default output format

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:

Command	Description
/model <name>	Switch model mid-conversation
/system <prompt>	Set the system prompt
/clear	Clear conversation history
/history	Show conversation history
`/save <file.json	file.md>`
/tokens	Show approximate token count
/help	Show REPL help
/exit	Exit the REPL

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

Error	Fix
API key not configured	Run cometapi init or set COMETAPI_KEY
Connection failed	Run cometapi doctor
Access token not configured	Set COMETAPI_ACCESS_TOKEN only when using account, stats, tokens, logs, or tasks

License

MIT