Metadata-Version: 2.4
Name: cometapi-cli
Version: 0.2.0
Summary: CometAPI CLI — official command-line interface for the CometAPI AI gateway
Project-URL: Homepage, https://github.com/cometapi-dev/cometapi-cli
Project-URL: Repository, https://github.com/cometapi-dev/cometapi-cli
Project-URL: Documentation, https://docs.cometapi.com
Project-URL: Changelog, https://github.com/cometapi-dev/cometapi-cli/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/cometapi-dev/cometapi-cli/issues
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/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> **Official command-line interface for [CometAPI](https://cometapi.com)** — 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

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

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

**Prerequisites**: Python 3.10+ · [Get your API key](https://www.cometapi.com/console/token)

## Quick Start

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

```bash
export COMETAPI_KEY="your-api-key"               # https://www.cometapi.com/console/token
export COMETAPI_ACCESS_TOKEN="your-access-token"  # https://www.cometapi.com/console/personal (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

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

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

### Logs

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

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

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

### Shell Completion

```bash
cometapi --install-completion
```

## Configuration

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

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

```bash
# 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](SKILL.md) for the full agent skill definition

## Development

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

<details>
<summary>Without uv (pip)</summary>

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

</details>

## 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](https://www.cometapi.com/console/token) · [Access Token](https://www.cometapi.com/console/personal)
- **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](CONTRIBUTING.md) for guidelines.

## License

This project is licensed under the [MIT License](LICENSE).

## License

MIT
