CPA Usage

Local CLIProxyAPI usage collector and dashboard, packaged as a Node.js CLI.

CPA Usage reads CLIProxyAPI's Redis-compatible usage queue, stores usage and configuration in SQLite, and serves a local dashboard for requests, token usage, accounts, models, failures, and recent traffic.

Supported service platforms: macOS and Ubuntu Server 24.04 LTS 64-bit. macOS uses a per-user LaunchAgent; Ubuntu uses a per-user systemd service.

Published on npm as cpa-usage.

Features

• npm-first install and run flow.
• Node.js 22.5+ runtime, using built-in node:sqlite.
• No runtime npm dependencies.
• SQLite persistence for usage records and local settings.
• Default data directory: ~/.cpa_usage.
• Vite + React dashboard served by the same local process.
• Local dashboard protected by an in-app management-key unlock screen.
• API-key-safe usage storage: request API keys are replaced with short SHA-256 fingerprints, and raw payload persistence is limited to known usage fields.

Install

npm install -g cpa-usage
cpa-usage init --management-key "your-management-key"

Open http://127.0.0.1:8848.

The first screen asks for the CLIProxyAPI management key. Use the Configuration page if you need to save or replace the key later.

Verify the installed CLI:

cpa-usage status

Requirements

• macOS, or Ubuntu Server 24.04 LTS 64-bit
• Node.js 22.5+
• npm
• CLIProxyAPI running locally, defaulting to 127.0.0.1:8317

Data Location

By default, all runtime data is stored in:

~/.cpa_usage/cpa_usage.sqlite

The SQLite database contains:

• usage records
• sanitized raw payloads
• deduplication hashes
• local settings, including the management key saved from --management-key or the dashboard settings page

Override the location:

cpa-usage init --data-dir ~/.cpa_usage_dev
cpa-usage init --db /absolute/path/to/cpa_usage.sqlite

Commands

CPA Usage runs as a user service after initialization:

cpa-usage init --management-key "your-management-key"

Then manage the service with:

cpa-usage status     # show service status
cpa-usage start      # start an initialized service
cpa-usage stop       # stop the service
cpa-usage restart    # restart the service
cpa-usage uninstall  # remove the service and ask whether to delete local data

On macOS, the service is installed as ~/Library/LaunchAgents/com.local.cpa-usage.plist. On Ubuntu Server 24.04 LTS 64-bit, it is installed as ~/.config/systemd/user/com.local.cpa-usage.service. init installs a service with automatic restart after crashes. start only starts an already initialized service.

For Ubuntu boot startup without an interactive login session, enable lingering for the service user:

loginctl enable-linger "$USER"

Common options:

cpa-usage init \
  --host 127.0.0.1 \
  --port 8848 \
  --cpa-host 127.0.0.1 \
  --cpa-port 8317

Environment overrides:

CPA_MGMT_KEY="your-management-key" cpa-usage init
CPA_USAGE_DB="/absolute/path/to/cpa_usage.sqlite" cpa-usage init
CPA_USAGE_WEB_DIST="/absolute/path/to/web/dist" cpa-usage init

CPA_MGMT_KEY is a runtime override for initialization. --management-key persists the key into SQLite.

Development

npm install
npm --prefix web ci
npm test
npm run build

For dashboard development, run the backend and Vite dev server in separate shells:

npm start -- --management-key "your-management-key"

npm run dev

Open http://127.0.0.1:5173; Vite proxies /api/* to the Node service on 8848.

npm Package

Package name: cpa-usage

The published package includes the Node CLI, server source, and built dashboard assets under dashboard/.

To inspect the package locally before a release:

npm pack --dry-run --ignore-scripts

Release maintainers can publish a new version with:

npm run build
npm publish --access public

Project Layout

.
├── bin/                    # npm executable entry point
├── src/                    # Node collector, SQLite store, HTTP server, CLI
├── tests/                  # node:test coverage
├── web/                    # Vite + React dashboard
├── docs/                   # development and publishing notes
├── package.json            # npm package metadata
└── README.md

Security Notes

• Keep the dashboard bound to 127.0.0.1 unless you put it behind trusted network controls.
• The dashboard uses an in-app unlock screen backed by an HTTP-only local session cookie. Do not expose it to an untrusted network.
• If the dashboard host is not loopback, CPA Usage refuses to start until a management key is already configured.
• The management key is stored in local SQLite when saved via --management-key or the dashboard settings page.
• Stored raw payload JSON is allowlisted to known usage fields and an API key fingerprint.
• The data directory is created with owner-only permissions where the platform supports it.
• cpa-usage uninstall always removes the service plist. It asks before deleting the SQLite database and logs; use --keep-data or --delete-data for scripts.

License

MIT. See LICENSE.