cometapi-cli 0.1.0__tar.gz

cometapi_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Test
+        run: uv run pytest -v --tb=short

cometapi_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cometapi_cli-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environment
+.venv/
+
+# Build artifacts
+dist/
+*.egg-info/
+
+# Environment
+.env
+.envrc
+
+# macOS
+.DS_Store

cometapi_cli-0.1.0/AGENTS.md

@@ -0,0 +1,486 @@
+# CometAPI CLI — Agent Instructions
+
+> This file covers CLI-specific details. For cross-cutting architecture, see the root [AGENTS.md](../AGENTS.md).
+
+## Overview
+
+The CLI is a Typer + Rich command-line tool that proxies all business logic through `cometapi-python`. It must **never** make direct HTTP requests — all network calls go through `CometClient` from the Python SDK.
+
+## Project Layout
+
+```
+cometapi-cli/
+├── pyproject.toml                      # Hatch build, deps, entry point
+├── uv.lock                             # Lock file (committed)
+├── SKILL.md                            # Agent capability description
+├── skills/
+│   └── live-test/
+│       └── SKILL.md                    # Live testing SOP for Coding Agents
+├── src/cometapi_cli/
+│   ├── __init__.py                     # __version__
+│   ├── app.py                          # Typer app, global options, command registration
+│   ├── main.py                         # Backward compat shim → app.py
+│   ├── config.py                       # Config file (~/.config/cometapi/config.toml), get_client()
+│   ├── constants.py                    # Shared constants (QUOTA_PER_UNIT, helpers)
+│   ├── console.py                      # Shared Rich Console instances
+│   ├── errors.py                       # CometCLIError hierarchy, exit codes, handle_errors decorator
+│   ├── formatters.py                   # Multi-format output (table/json/yaml/csv/markdown)
+│   └── commands/
+│       ├── __init__.py
+│       ├── chat.py                     # chat send (streaming + JSON), REPL entry
+│       ├── chat_repl.py               # Multi-turn chat REPL with prompt_toolkit
+│       ├── models.py                   # models list with search/limit
+│       ├── balance.py                  # account balance
+│       ├── account.py                  # user profile (access_token)
+│       ├── stats.py                    # usage statistics (access_token)
+│       ├── tokens.py                   # API key listing and search (access_token)
+│       ├── logs.py                     # Usage logs browsing and filtering (access_token)
+│       ├── tasks.py                    # Async task logs — Suno, MJ, Luma, Kling (access_token)
+│       ├── config_cmd.py              # init wizard + config show/set/unset/path
+│       ├── doctor.py                   # connectivity & config diagnostics
+│       └── repl.py                     # Full command REPL (interactive shell)
+└── tests/
+    ├── __init__.py
+    ├── conftest.py                     # Shared fixtures, mock client factory
+    ├── test_help.py                    # Version, help, command listing tests
+    ├── test_chat.py                    # Chat command tests
+    ├── test_config.py                  # Config read/write/CLI tests
+    ├── test_doctor.py                  # Doctor diagnostics tests
+    ├── test_errors.py                  # Error types and exit codes
+    ├── test_formatters.py             # Multi-format output tests
+    ├── test_models.py                  # Models command tests
+    ├── test_balance.py                 # Balance command tests (incl. --source)
+    ├── test_account.py                 # Account command tests
+    ├── test_stats.py                   # Stats command tests
+    ├── test_tokens.py                  # Tokens command tests
+    ├── test_logs.py                    # Logs command tests
+    └── test_tasks.py                   # Tasks command tests
+```
+
+## Key Design Decisions
+
+- **Self-contained client.** `cometapi_cli/client.py` contains `CometClient` (inherits `openai.OpenAI`). The CLI has **no dependency** on the `cometapi` Python SDK package.
+- **No direct HTTP for OpenAI-compatible endpoints.** Always use inherited methods via `CometClient`. Only CometAPI-specific endpoints use `self._client.request()` directly.
+
+## Model ID Policy
+
+The default model constant lives in `config.py:get_default_model()`. All examples, defaults, and test fixtures MUST use current model IDs — see the root [AGENTS.md](../AGENTS.md) for the authoritative list.
+
+## Security & Credential Policy
+
+All user-facing messages involving missing or invalid credentials MUST include the relevant creation URL:
+- API Key: https://www.cometapi.com/console/token
+- Access Token: https://www.cometapi.com/console/personal
+
+See the root [AGENTS.md](../AGENTS.md) for the full security policy.
+- **Entry point:** `cometapi = "cometapi_cli.app:app"` — the command name is `cometapi`.
+
+## Publishing to PyPI
+
+Package name: `cometapi-cli`. Triggered automatically by pushing a `v*` tag to GitHub.
+
+### Release SOP
+
+```bash
+# 1. Bump version in TWO places (must match):
+#    - pyproject.toml: version = "X.Y.Z"
+#    - src/cometapi_cli/__init__.py: __version__ = "X.Y.Z"
+
+# 2. Commit and push
+git add -A
+git commit -m "release: vX.Y.Z"
+git push origin main
+
+# 3. Tag and push — triggers publish.yml automatically
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+### Verify
+
+```bash
+open https://pypi.org/project/cometapi-cli/
+pip install cometapi-cli==X.Y.Z
+cometapi --version
+```
+
+### Version sync rule
+
+`pyproject.toml` `version` and `src/cometapi_cli/__init__.py` `__version__` **must always match**.
+
+## Configuration
+- **Output formats:** Every data command supports `--json` (per-command) and global `--format/-f` (table/json/yaml/csv/markdown). Persistent default can be set via `output_format` in config.toml.
+- **Error handling:** All commands wrapped with `@handle_errors` decorator that catches SDK/network errors and maps to user-friendly messages + Unix exit codes.
+- **Exit codes:** sysexits.h compatible: 0=success, 1=error, 2=usage, 64=config missing, 69=service unavailable, 77=auth error, 78=config error.
+
+## Commands — Complete Reference
+
+> **Maintenance rule:** Any CLI interface change (new command, renamed flag, new option) **must** update this section. This is the single source of truth for what the CLI exposes.
+
+### Global Options
+
+These options apply to **every** command via the root Typer callback.
+
+| Option | Alias | Type | Default | Description |
+|--------|-------|------|---------|-------------|
+| `--version` | `-V` | flag | — | Print version (`cli`, `sdk`, `python`) and exit |
+| `--format` | `-f` | `table\|json\|yaml\|csv\|markdown` | `table` | Global output format (overridden by per-command `--format` or `--json`) |
+| `--json` | — | flag | `false` | Shortcut for `--format json` |
+| `--help` | `-h` | flag | — | Show help for any command |
+| `--install-completion` | — | flag | — | Install shell completion (bash/zsh/fish/powershell) |
+| `--show-completion` | — | flag | — | Print the completion script |
+
+**Output format resolution priority:** per-command `--json` > per-command `--format` > global `--format` > `table`.
+
+---
+
+### `chat` — Send a chat message or start interactive REPL
+
+**Auth:** `COMETAPI_KEY`
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `MESSAGE` | — | argument (positional, optional) | `None` | Message to send. Omit to enter interactive multi-turn REPL. |
+| `--model` | `-m` | `str` | config `default_model` or `gpt-5.4` | Model to use |
+| `--system` | `-s` | `str` | `None` | System prompt prepended to conversation |
+| `--temperature` | `-t` | `float` | API default | Sampling temperature (0.0–2.0) |
+| `--max-tokens` | — | `int` | API default | Maximum tokens in the response |
+| `--stream/--no-stream` | — | flag | `--stream` | Enable/disable streaming output |
+| `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
+| `--json` | — | flag | `false` | Output structured JSON (disables streaming) |
+
+**Behavior:**
+- With `MESSAGE`: sends a single request, streams response to stdout. With `--json`, returns `{"model", "role", "content", "usage"}`.
+- Without `MESSAGE`: enters interactive multi-turn Chat REPL (see [Chat REPL Slash Commands](#chat-repl-slash-commands) below).
+- Model resolved via: `--model` flag > config `default_model` > `gpt-5.4`.
+
+**JSON output schema:**
+```json
+{
+  "model": "gpt-5.4",
+  "role": "assistant",
+  "content": "...",
+  "usage": { "prompt_tokens": 9, "completion_tokens": 10, "total_tokens": 19 }
+}
+```
+
+---
+
+### `models` — List available models
+
+**Auth:** `COMETAPI_KEY`
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `--search` | `-s` | `str` | `None` | Filter models by name (case-insensitive substring match) |
+| `--limit` | `-l` | `int` | `None` (show all) | Maximum number of models to display |
+| `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
+| `--json` | — | flag | `false` | Output as JSON |
+
+**Behavior:** Fetches all models via `client.models.list()`, sorts alphabetically by `id`, applies `--search` filter, then `--limit` truncation.
+
+**Table columns:** `id` (cyan), `owned_by` (green).
+
+---
+
+### `balance` — Show account balance
+
+**Auth:** `COMETAPI_KEY` (always), `COMETAPI_ACCESS_TOKEN` (for account-level view)
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `--source` | `-s` | `str` (`account` or `token`) | `None` (auto-detect) | Force data source: `account` = full account balance via `/api/user/self`; `token` = per-API-key billing via `/v1/dashboard/billing/*` |
+| `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
+| `--json` | — | flag | `false` | Output raw balance dict as JSON |
+
+**Auto-detection logic** (when `--source` is omitted):
+1. If `COMETAPI_ACCESS_TOKEN` is available → uses `account` source.
+2. Otherwise → falls back to `token` (per-key billing) source.
+
+**Display — `account` source:**
+| Field | Description |
+|-------|-------------|
+| Available Balance | Current remaining balance (USD) |
+| Used | Total amount consumed (USD) |
+| Total Topped Up | Lifetime top-up amount (USD) |
+
+**Display — `token` (billing) source:**
+| Field | Description |
+|-------|-------------|
+| Limit | Spending cap (`Unlimited` if no cap set) |
+| Used | Amount consumed through this API key (USD) |
+
+---
+
+### `account` — Show account profile
+
+**Auth:** `COMETAPI_ACCESS_TOKEN` (required)
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
+| `--json` | — | flag | `false` | Output full profile as JSON |
+
+**Display fields:** `id`, `username`, `display_name`, `email`, `role`, `status`.
+
+---
+
+### `stats` — Show usage statistics
+
+**Auth:** `COMETAPI_ACCESS_TOKEN` (required)
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
+| `--json` | — | flag | `false` | Output raw stats as JSON |
+
+**Display fields:** `requests`, `request_rate_change`, `usage` (USD), `usage_rate_change`, `success_rate`, `predicted_days_left`.
+
+---
+
+### `tokens` — List and search API keys
+
+**Auth:** `COMETAPI_ACCESS_TOKEN` (required)
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `--search` | `-s` | `str` | `None` | Search tokens by name or key substring (uses `/api/token/search`) |
+| `--page` | `-p` | `int` | `1` | Page number for paginated results |
+| `--limit` | `-l` | `int` | `20` | Results per page |
+| `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
+| `--json` | — | flag | `false` | Output raw token list as JSON |
+
+**Behavior:**
+- Without `--search`: calls `client.list_tokens(page=, page_size=)` — paginated, returns `data.items`.
+- With `--search`: calls `client.search_tokens(keyword=)` — flat `data` list, ignores `--page`/`--limit`.
+
+**Table columns:** `id` (cyan), `name` (green), `key` (yellow, masked), `status` (green — active/disabled/expired/exhausted), `balance` (green, USD or "Unlimited"), `used` (red, USD), `created` (dim), `accessed` (dim), `expires` (dim, "Never" if -1).
+
+**Key masking:** Only the last 4 characters are shown, e.g., `****abcd`.
+
+---
+
+### `logs` — Show usage logs
+
+**Auth:** `COMETAPI_ACCESS_TOKEN` (required)
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `--model` | `-m` | `str` | `None` | Filter by model name |
+| `--token-name` | `-t` | `str` | `None` | Filter by token name |
+| `--type` | — | `str` | `None` | Filter by log type (see values below) |
+| `--search` | `-s` | `str` | `None` | Search logs by keyword (uses `/api/log/self/search`) |
+| `--start` | — | `str` | `None` | Start date (`YYYY-MM-DD`, ISO 8601, or Unix timestamp) |
+| `--end` | — | `str` | `None` | End date (`YYYY-MM-DD`, ISO 8601, or Unix timestamp) |
+| `--group` | `-g` | `str` | `None` | Filter by API key group |
+| `--page` | `-p` | `int` | `1` | Page number |
+| `--limit` | `-l` | `int` | `20` | Results per page |
+| `--export` | — | flag | `false` | Export logs as server-side CSV to stdout |
+| `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
+| `--json` | — | flag | `false` | Output raw log list as JSON |
+
+**Valid `--type` values:**
+
+| Value | Backend code | Description |
+|-------|-------------|-------------|
+| `unknown` | 0 | Unknown log type |
+| `topup` | 1 | Balance top-up |
+| `consume` | 2 | API consumption |
+| `manage` | 3 | Management action |
+| `system` | 4 | System event |
+| `error` | 5 | Error log |
+| `refund` | 6 | Refund |
+
+Invalid `--type` values produce an error message with valid options and exit code 2.
+
+**Behavior:**
+- Without `--search` or `--export`: calls `client.list_logs(page=, page_size=, log_type=, model_name=, token_name=, start_timestamp=, end_timestamp=, group=)` — paginated, `data.items`.
+- With `--search`: calls `client.search_logs(keyword=)` — flat `data` list, ignores other filter flags.
+- With `--export`: calls `client.export_logs(...)` — writes server-side CSV bytes to stdout. Honors `--model`, `--token-name`, `--type`, `--start`, `--end`, `--group`. Pipe-friendly (no Rich formatting).
+
+**Date parsing:** `--start` and `--end` accept `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS` (ISO 8601), or raw Unix timestamps. Dates are interpreted as UTC.
+
+**Table columns:** `time` (dim), `type` (cyan), `model` (green), `token` (yellow), `prompt` (tokens count), `completion` (tokens count), `cost` (red, USD), `duration_ms`, `stream` (Yes/No).
+
+---
+
+### `tasks` — Show async task logs
+
+**Auth:** `COMETAPI_ACCESS_TOKEN` (required)
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `--platform` | `-p` | `str` | `None` | Filter by platform (see values below) |
+| `--task-id` | — | `str` | `None` | Filter by task ID |
+| `--status` | `-s` | `str` | `None` | Filter by status (see values below) |
+| `--action` | `-a` | `str` | `None` | Filter by action type (e.g., `MUSIC`, `generate`) |
+| `--start` | — | `str` | `None` | Start date (`YYYY-MM-DD`, ISO 8601, or Unix timestamp) |
+| `--end` | — | `str` | `None` | End date (`YYYY-MM-DD`, ISO 8601, or Unix timestamp) |
+| `--page` | — | `int` | `1` | Page number |
+| `--limit` | `-l` | `int` | `20` | Results per page |
+| `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
+| `--json` | — | flag | `false` | Output raw task list as JSON |
+
+**Valid `--platform` values:** `suno`, `mj`, `luma`, `replicate`, `kling`, `runwayml`, `runway`, `jimeng`, `volcengine`, `sora`, `bria`, `flux`
+
+**Valid `--status` values:** `SUBMITTED`, `QUEUED`, `IN_PROGRESS`, `FAILURE`, `SUCCESS`, `UNKNOWN` (case-insensitive input, sent as uppercase)
+
+Invalid `--platform` or `--status` values produce an error message with valid options and exit code 2.
+
+**Behavior:** Calls `client.list_tasks(page=, page_size=, platform=, task_id=, status=, action=, start_timestamp=, end_timestamp=)` — paginated response via `GET /api/task/self`.
+
+**Table columns:** `time` (dim), `platform` (magenta), `task_id` (cyan), `action` (yellow), `status` (green), `model` (green), `progress` (dim), `cost` (red, USD), `duration` (dim, submit-to-finish).
+
+---
+
+### `init` — Interactive setup wizard
+
+**Auth:** None (creates auth config)
+
+No options. Launches an interactive Rich prompt that:
+1. Collects `api_key` (with connectivity test).
+2. Optionally collects `access_token`.
+3. Sets `default_model`.
+4. Saves to `~/.config/cometapi/config.toml` with 0600 permissions.
+5. Displays security disclaimer and credential creation URLs.
+
+---
+
+### `doctor` — Run diagnostics and health checks
+
+**Auth:** None (inspects current config)
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
+| `--json` | — | flag | `false` | Output diagnostics as JSON |
+
+**Checks performed:**
+1. Config file existence (`~/.config/cometapi/config.toml`)
+2. API key presence and source (environment / config / none)
+3. API connectivity (calls `client.models.list()`)
+4. Access token presence
+5. SDK installation
+6. Version info (Python, SDK, CLI)
+
+Exits with code 64 if any critical check fails.
+
+---
+
+### `repl` — Interactive command shell
+
+**Auth:** None (individual commands within REPL check auth as needed)
+
+No options. Starts a `prompt_toolkit` session with:
+- Tab completion for all commands and common flags (`--json`, `--format`, `--model`, `--system`, `--search`, `--limit`, `--page`, `--type`, `--token-name`, `--help`).
+- Persistent history in `~/.config/cometapi/repl_history`.
+- Dispatches typed commands through the Typer app (no `cometapi` prefix needed).
+- Built-in `help` and `exit`/`quit` commands.
+- Prevents recursive `repl` invocation.
+
+---
+
+### `config` — Manage CLI configuration
+
+A subcommand group with four subcommands:
+
+#### `config show` — Display current configuration
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
+| `--json` | — | flag | `false` | Output as JSON |
+
+Secrets (`api_key`, `access_token`) are always masked in output.
+
+#### `config set` — Set a configuration value
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `KEY` | argument (required) | Configuration key (see valid keys below) |
+| `VALUE` | argument (required) | Value to set |
+
+#### `config unset` — Remove a configuration value
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `KEY` | argument (required) | Configuration key to remove |
+
+#### `config path` — Show the configuration file path
+
+No options. Prints the absolute path to `config.toml`.
+
+**Valid config keys:** `api_key`, `access_token`, `base_url`, `default_model`, `output_format`.
+
+---
+
+### Chat REPL Slash Commands
+
+When `cometapi chat` is started without a message, these slash commands are available inside the REPL:
+
+| Command | Description |
+|---------|-------------|
+| `/model <name>` | Switch model mid-conversation. Without arg: show current model. |
+| `/system <prompt>` | Set system prompt. Without arg: show current system prompt. |
+| `/clear` | Clear conversation history (preserves system prompt). |
+| `/history` | Display all messages in the conversation. |
+| `/save <file.json\|file.md>` | Export conversation to JSON or Markdown file. |
+| `/tokens` | Show approximate token count and message count. |
+| `/help` | List all slash commands. |
+| `/exit` | Exit the chat REPL (also Ctrl+D, `/quit`, `/q`). |
+
+---
+
+### Exit Codes
+
+| Code | Constant | Meaning |
+|------|----------|---------|
+| `0` | `SUCCESS` | Command completed successfully |
+| `1` | `ERROR` | General runtime error |
+| `2` | `USAGE` | Invalid usage (bad arguments, unknown `--type` value, etc.) |
+| `64` | `CONFIG_MISSING` | Required configuration (API key) not set |
+| `69` | `SERVICE_UNAVAILABLE` | API endpoint unreachable |
+| `77` | `AUTH_ERROR` | Authentication failed (invalid key or token) |
+| `78` | `CONFIG_ERROR` | Configuration file corrupt or unreadable |
+
+---
+
+## Build & Test
+
+```bash
+uv sync                         # Install deps (links local cometapi-python)
+uv run cometapi --version        # Verify CLI version
+uv run cometapi -h               # List all commands
+uv run cometapi doctor           # Check configuration health
+uv run pytest -v                 # Run tests (98 tests)
+uv run ruff check src/ tests/    # Lint
+```
+
+## Architecture Conventions
+
+- Framework: **Typer** with `rich_markup_mode="rich"` and `no_args_is_help=True`.
+- UI: **Rich** for tables, panels, markdown rendering, and console formatting.
+- Module name: `cometapi_cli` (underscore). Package name: `cometapi-cli` (hyphen).
+- All commands use `typer.Option()` with `Annotated` type hints.
+- Error messages via `err_console.print()` (stderr) with `[red bold]Error:[/]` markup.
+- Config file: TOML format at `~/.config/cometapi/config.toml`, 0600 permissions.
+- Valid config keys: `api_key`, `access_token`, `base_url`, `default_model`, `output_format`.
+- Client creation via `config.get_client()` — resolves auth from env vars + config file.
+
+## Environment Variables
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `COMETAPI_KEY` | Yes (for chat/balance/models) | API key for AI relay |
+| `COMETAPI_ACCESS_TOKEN` | Yes (for account/stats/tokens/logs) | Access token for account mgmt |
+| `COMETAPI_BASE_URL` | No | Override default base URL |
+
+## Dependencies
+
+- `cometapi` — CometAPI Python SDK (local editable in dev)
+- `typer>=0.12` — CLI framework
+- `rich>=13.0` — Terminal UI
+- `tomli>=2.0` — TOML reading (Python 3.10 only; 3.11+ uses stdlib `tomllib`)
+- `tomli-w>=1.0` — TOML writing
+- `pyyaml>=6.0` — YAML output format
+- `prompt-toolkit>=3.0` — REPL line editing, history, completion

cometapi_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] — 2026-04-09
+
+### Added
+
+- **12 commands**: `chat`, `models`, `balance`, `account`, `stats`, `tokens`, `logs`, `tasks`, `init`, `doctor`, `repl`, `config`
+- **Chat REPL**: multi-turn interactive chat with slash commands (`/model`, `/system`, `/clear`, `/history`, `/save`, `/tokens`)
+- **Command REPL**: interactive shell with tab completion and persistent history
+- **Multi-format output**: table, JSON, YAML, CSV, Markdown via `--format` / `--json`
+- **Logs**: date range filtering (`--start`, `--end`), group filtering (`--group`), CSV export (`--export`), request detail (`--request-id --detail`)
+- **Tasks**: async task logs for Suno, Midjourney, Luma, Kling, and other platforms
+- **Config management**: `config show/set/unset/path` subcommands, TOML config at `~/.config/cometapi/config.toml`
+- **Persistent output_format**: set default output format in `config.toml`
+- **Doctor diagnostics**: connectivity, auth, SDK, and config health checks
+- **Setup wizard**: `cometapi init` with API key validation
+- **Shell completion**: bash, zsh, fish, powershell
+- **Error handling**: structured exit codes (sysexits.h compatible), user-friendly messages
+- **Security**: credential masking, 0600 file permissions, creation URL guidance
+- **CI/CD**: GitHub Actions for testing (Python 3.10–3.13) and PyPI publishing
+
+### Changed
+
+- **Config priority**: `CLI flags > config.toml > env vars > defaults` (config file takes precedence over environment variables)
+- Shared constants module — extracted `QUOTA_PER_UNIT`, `quota_to_usd`, `format_ts`, `parse_date`, `extract_items` from duplicated command code
+
+### Fixed
+
+- `chat` command now supports `--format` option (was only `--json`)
+- `tokens --search` now applies `--limit` for client-side truncation
+- `logs --search` warns when other filters are silently ignored
+- Corrupt config files now raise `ConfigError` (exit code 78) instead of silently returning empty config
+- `get_default_model()` now respects `COMETAPI_DEFAULT_MODEL` environment variable
+
+## [0.1.0] — 2026-04-07
+
+### Added
+
+- Initial release
+- Core commands: `chat`, `models`, `balance`, `init`, `doctor`
+- Basic config file support

cometapi_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CometAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.