CPA Usage Keeper: A SQLite-Backed Dashboard for CLIProxyAPI Usage Data

The Problem It Solves

CLIProxyAPI (CPA) is a proxy that routes AI requests, but it does not appear to offer a built-in persistence layer for usage history. CPA Usage Keeper fills that gap by collecting usage data from a CPA instance, storing it in SQLite, and exposing a dashboard for analysis. This is for operators who need more than real-time metrics: they want historical trends, cost breakdowns, and per-API-key views. The README positions it as a standalone tool, meaning it does not require modifying CPA itself. It targets individuals or teams running CPA who want to answer questions like 'which model consumed the most tokens last week' or 'what is the cache hit rate for this key'. Without such a tool, you would have to rely on CPA's own logs or build your own collector, which is exactly the problem this project addresses.

How It Works: Polling, SQLite, and a Web UI

The architecture is visible from the project structure. The cmd/server directory holds the entry point, internal/poller handles CPA usage and metadata synchronization, internal/repository manages SQLite persistence and aggregations, and internal/api exposes HTTP routes. The frontend is a separate web app under ./web, which proxies /api to the backend. The poller periodically fetches usage data from CPA, including requests, tokens, cost, cache usage, success rate, RPM/TPM, and latency. This data is written to SQLite, and the dashboard reads from that store. The README mentions 'subscription mode' for multiple collectors, which suggests the poller can subscribe to CPA events rather than only polling on a schedule. This is a key mechanism: if you run more than one collector against the same CPA instance, all of them must use subscription mode, otherwise collection may stop or become incomplete. That is a specific operational constraint, not a generic feature list.

Getting It Running: Real Commands and Config Keys

The quick start path begins with a prerequisite: you must enable usage statistics in CPA by setting usage-statistics-enabled: true. Without that, Keeper has nothing to collect. For local development, the README instructs you to copy .env.example to .env and set at least CPA_BASE_URL and CPA_MANAGEMENT_KEY. Then you start the backend with go run ./cmd/server/main.go and the frontend with npm --prefix ./web ci followed by npm --prefix ./web run dev -- --host 127.0.0.1. The frontend proxies /api to http://127.0.0.1:8080 by default, overridable with VITE_API_PROXY_TARGET. For production, Docker Compose is recommended, with separate stacks for a new CPA plus Keeper deployment versus Keeper-only when CPA already exists. Login protection is enabled by default; you must set LOGIN_PASSWORD before starting, or explicitly set AUTH_ENABLED=false only if the network is isolated. These are concrete, actionable steps, not vague advice.

Limitations and Failure Modes

The most obvious limitation is that Keeper is useless without CPA. It is not a general-purpose usage tracker; it is tightly coupled to CLIProxyAPI's data format and configuration. The README also warns about a specific failure mode: if multiple usage collectors share one CPA instance and not all use subscription mode, collection may stop or become incomplete. That is a real operational trap. Another constraint is that login protection is on by default, which is good for security but means an extra configuration step; if you forget to set LOGIN_PASSWORD, the service may not start or may be inaccessible. The README does not mention any built-in rate limiting or multi-user role management beyond a simple password, so this is not a team-wide analytics platform with fine-grained access control. For large-scale deployments, the benchmark report exists, but the README does not summarize its numbers, so you cannot judge capacity without reading that separate document. That is a gap in the main documentation.

Alternatives and How They Differ

The natural alternative is to build your own logging pipeline from CPA's raw output, or to rely on CPA's own logging if it has any. The key difference is that Keeper provides a ready-made SQLite schema and a web dashboard, saving you from writing your own aggregation queries and UI. Another alternative is to use a generic metrics system like Prometheus with Grafana, which would require you to write an exporter for CPA and design your own dashboards. That approach gives you more flexibility in storage and alerting, but it is far more work. Keeper's approach is opinionated: it stores data in a single SQLite file, which is simple to back up and move, but it does not scale to massive multi-node setups as naturally as a time-series database. The README mentions optional scheduled backups, which is a plus for SQLite's single-file nature. If you already run Prometheus, the generic route might fit your stack better, but if you want a turnkey solution, Keeper is the more direct path.

Maintenance and Upgrade Considerations

The project is under active development, with releases v1.14.7 through v1.14.9 pushed within a few days in August 2026. That suggests a steady release cadence, which is good for bug fixes but also means you should watch for breaking changes between versions. The README does not provide a migration guide, so upgrading may involve checking release notes manually. The license is MIT, which is permissive and allows commercial use, but you are responsible for your own compliance. The project depends on Go 1.26+ and Node.js 24+ for local development, which are relatively recent versions; if your environment is behind on those, you may face build issues. The Docker images are published for linux/amd64 and linux/arm64, so architecture support is broad. Since the tool stores data in SQLite, backups are straightforward: copy the database file. The README mentions optional scheduled backups, but does not specify the mechanism, so you will need to check the configuration files for that feature.

Who Should Adopt It and What to Verify First

This tool is for CPA users who need historical usage data and do not want to build a dashboard from scratch. It is not for people who are not running CPA, nor for those who need a multi-tenant analytics platform with role-based access. Before adopting, verify that your CPA instance has usage-statistics-enabled: true, and if you have multiple collectors, confirm they all use subscription mode. Also check the latest release notes for any changes to configuration keys like CPA_BASE_URL or LOGIN_PASSWORD. The README suggests a benchmark report exists, so if you are planning a high-throughput deployment, read internal/benchmark/REPORT.md to understand capacity limits. The project is MIT-licensed, so licensing is not a barrier, but you should still review the license file for any third-party dependencies. Overall, if you fit the CPA user profile, this is a practical tool; if not, look elsewhere.

Editorial conclusion

Adopt CPA Usage Keeper if you run CLIProxyAPI and need persistent, queryable usage data with a built-in dashboard, especially if you prefer Docker Compose or Homebrew. Avoid it if you do not use CPA, or if you cannot enable usage-statistics-enabled: true, as the tool depends on that upstream setting. Before deploying, verify that your CPA instance supports subscription mode when you have multiple collectors, and confirm that LOGIN_PASSWORD is set or AUTH_ENABLED=false is intentional. The project is MIT-licensed and under active release, but you should check the latest release notes for breaking changes before upgrading.

Official sources

1. Official README
2. Project repository
3. Release notes