cometapi-cli 0.2.1

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

CometAPI CLI

Official command-line interface for CometAPI — 500+ AI Model API, All In One API.

Access 500+ AI models at low cost, directly from the terminal. Chat, search models, check usage, and manage your account — all through a single API key.

Features: multi-model chat (streaming + REPL) · model search · account & usage stats · diagnostics · multi-format output (table/JSON/YAML/CSV/Markdown) · agent-native design · TOML config · shell completion

Installation

pip install cometapi-cli

pipx install cometapi-cli    # isolated environment
uv tool install cometapi-cli  # uv

Prerequisites: Python 3.10+ · CometAPI Key

Quick Start

# 1. Run the setup wizard
cometapi init

# 2. Chat with a model
cometapi chat "Explain quantum computing in one sentence"

# 3. List available models
cometapi models --search gpt --limit 10

Or configure manually:

export COMETAPI_KEY="your-api-key"               # https://www.cometapi.com/console/token?utm_source=cometapi-cli&utm_medium=readme&utm_campaign=oss&utm_content=env-api-key
export COMETAPI_ACCESS_TOKEN="your-access-token"  # https://www.cometapi.com/console/personal?utm_source=cometapi-cli&utm_medium=readme&utm_campaign=oss&utm_content=env-access-token (optional)

Commands

Command	Description
chat [MESSAGE]	Send a message or start interactive chat REPL (no args)
models	List available models (--search, --limit)
balance	Show account balance
account	Show account profile (requires access token)
stats	Show usage statistics (requires access token)
tokens	List and search your API keys (requires access token)
logs	Show usage logs with filters (requires access token)
tasks	Show async task logs (requires access token)
init	Interactive setup wizard
doctor	Run diagnostics and health checks
repl	Start interactive command shell
config	Manage CLI configuration (show, set, unset, path)

Chat

cometapi chat "Hello!"                                          # Streaming
cometapi chat "Summarize this" --model claude-sonnet-4-6 --system "Be concise"
cometapi chat "Hello" --json                                    # JSON output
cometapi chat                                                   # Interactive REPL

Chat REPL commands: /model, /system, /clear, /history, /save, /tokens, /help, /exit

Models

cometapi models                        # List all
cometapi models --search claude        # Search by name
cometapi models --limit 5 --json       # JSON output

Logs

cometapi logs                          # Recent usage logs
cometapi logs --model gpt-5.4         # Filter by model
cometapi logs --start 2026-04-01       # Date filter
cometapi logs --export > usage.csv     # CSV export
cometapi logs --limit 50 --json        # JSON output

Tasks

cometapi tasks                         # Recent task logs
cometapi tasks --platform suno         # Filter by platform
cometapi tasks --status SUCCESS        # Filter by status
cometapi tasks --json                  # JSON output

Output Formats

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

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

Shell Completion

cometapi --install-completion

Configuration

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

cometapi config show              # View current config
cometapi config set api_key sk-…  # Set a value
cometapi config unset api_key     # Remove a value
cometapi config path              # Show config file path

Examples

# Switch default output to JSON (all commands)
cometapi config set output_format json

# Change default model
cometapi config set default_model claude-sonnet-4-6

# Override per-command (regardless of config)
cometapi models --format yaml
cometapi balance --json

Priority: CLI flags > config file > environment variables > defaults

Key	Env Variable	Description
api_key	COMETAPI_KEY	API key (required)
access_token	COMETAPI_ACCESS_TOKEN	Access token for account commands
base_url	COMETAPI_BASE_URL	API base URL
default_model	COMETAPI_DEFAULT_MODEL	Default model (fallback: gpt-5.4)
output_format	—	Default output format (table, json, yaml, csv, markdown)

Agent Integration

CometAPI CLI is designed to be agent-friendly:

• All data commands support --json for structured, machine-readable output
• Deterministic exit codes (0=success, 64=config missing, 77=auth error, 69=service unavailable)
• Errors on stderr, data on stdout
• See SKILL.md for the full agent skill definition

Development

git clone https://github.com/cometapi-dev/cometapi-cli.git
cd cometapi-cli
uv sync --extra dev

uv run pytest -v              # tests
uv run ruff check src/ tests/ # lint
uv run cometapi --version     # verify

Without uv (pip)

git clone https://github.com/cometapi-dev/cometapi-cli.git
cd cometapi-cli
pip install -e ".[dev]"
pytest -v

Security

• API keys and access tokens are never logged or displayed in full — only the last 4 characters are shown
• Config files are stored with restrictive permissions (0600)
• Credentials should never be committed to version control
• Create credentials at: API Key · Access Token
• Disclaimer: You are responsible for all usage and charges incurred with your API keys

Troubleshooting

Error	Solution
API key not configured	Run cometapi init or set COMETAPI_KEY env var
Connection failed	Run cometapi doctor to diagnose connectivity
Access token not configured	Only needed for account/stats commands — run cometapi init to add one

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License.