Metadata-Version: 2.4
Name: cometapi-cli
Version: 0.3.1
Summary: CometAPI CLI — official command-line interface for the CometAPI AI gateway
Project-URL: Homepage, https://pypi.org/project/cometapi-cli/
Project-URL: Documentation, https://apidoc.cometapi.com/libraries/cli/overview
Author-email: CometAPI <support@cometapi.com>
License: MIT
License-File: LICENSE
Keywords: ai,api-gateway,chat,cli,cometapi,llm,openai,streaming
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: openai>=1.0.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# CometAPI CLI

[![PyPI](https://img.shields.io/pypi/v/cometapi-cli)](https://pypi.org/project/cometapi-cli/)
[![Python](https://img.shields.io/pypi/pyversions/cometapi-cli)](https://pypi.org/project/cometapi-cli/)

Official command-line interface for [CometAPI](https://www.cometapi.com/?utm_source=cometapi-cli&utm_medium=readme&utm_campaign=pypi&utm_content=homepage), a multi-model AI gateway for GPT, Claude, Gemini, image, audio, and video models.

The [PyPI package page](https://pypi.org/project/cometapi-cli/) is the public homepage for installation and release metadata. The public documentation is available at [CometAPI CLI docs](https://apidoc.cometapi.com/libraries/cli/overview).

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

```bash
pip install cometapi-cli
```

You can also install it in an isolated tool environment:

```bash
pipx install cometapi-cli
uv tool install cometapi-cli
```

Create an API key in the [CometAPI console](https://www.cometapi.com/console/token?utm_source=cometapi-cli&utm_medium=readme&utm_campaign=pypi&utm_content=api-key). Account-management commands can also use an optional [access token](https://www.cometapi.com/console/personal?utm_source=cometapi-cli&utm_medium=readme&utm_campaign=pypi&utm_content=access-token).

## Quick start

Run the setup wizard:

```bash
cometapi init
```

Or configure credentials with environment variables:

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

```bash
cometapi --version
cometapi -h
cometapi doctor
```

Send a chat message:

```bash
cometapi chat "Explain quantum computing in one sentence"
```

Search the model catalog:

```bash
cometapi models --search gpt --limit 10
```

Inspect one model:

```bash
cometapi model info your-model-id
```

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

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

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

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

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

```bash
# 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:

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

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

Set a persistent default format:

```bash
cometapi config set output_format json
```

## Configuration

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

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

```bash
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>` | Save the session |
| `/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
