This project provides a standalone service for tracking and analyzing the usage of CliProxyAPI (CPA). It addresses the need for persistent storage and detailed statistical insights beyond CPA's core functionality, targeting CPA users who require monitoring of request volume, costs, performance, and model/API key composition. The primary benefit is a comprehensive, persistent dashboard offering deep visibility into API interactions.

How It Works

CPA Usage Keeper acts as a layer on top of CPA, consuming usage events from CPA's Redis queue and persisting them into an SQLite database. It periodically synchronizes CPA metadata and exposes aggregation APIs. The core architecture involves background workers that poll Redis for usage data, store it locally, and a web server that serves a React-based dashboard. This approach allows for offline data analysis, detailed filtering, and historical trend tracking without directly querying the live CPA instance for historical data.

Quick Start & Requirements

• Primary Install/Run: Docker Compose (recommended), Docker, Homebrew (macOS), or Linux binary.
• Prerequisites: A running CLIProxyAPI (CPA) instance with usage-statistics-enabled: true. Development requires Go 1.26+ and Node.js 22+.
• Configuration: Requires setting CPA_BASE_URL, CPA_MANAGEMENT_KEY, and optionally AUTH_ENABLED and LOGIN_PASSWORD via .env file or environment variables.
• Links: Docker Compose example provided in README. Homebrew tap: Willxup/cpa-usage-keeper.

Highlighted Details

• Persists CPA usage data to SQLite with configurable retention.
• Built-in dashboard visualizes request volume, token usage, cost, cache hits, success rates, and request latency.
• Offers granular filtering by time range, model, API Key, source, and request result.
• Features an analysis page for usage trends, cost breakdowns, provider composition, and hourly heatmaps.
• Includes a dedicated page for querying usage by CPA API Key and managing provider quotas.
• Supports optional password protection for the dashboard and automatic SQLite backups.

Maintenance & Community

The project acknowledges contributions and support from CLIProxyAPI, @YouShouldBetOnMe, and the CPA discussion group. No specific community channels (like Discord/Slack) or public roadmaps are detailed in the provided text.

Licensing & Compatibility

• License: MIT License.
• Compatibility: The MIT license is permissive, allowing for commercial use and integration into closed-source projects.

Limitations & Caveats

Setup requires a pre-existing, correctly configured CPA instance. While the dashboard offers extensive features, security notes highlight that SQLite backups are unencrypted, and sensitive data in browser-facing APIs is redacted but remains in the raw database. Public deployments necessitate enabling authentication and terminating HTTPS at a reverse proxy.