CLI Consumption

CLI Consumption measures how AI coding CLIs use models, tokens, tools, conversations, and turns. It runs locally, can consolidate copied data from several machines, and can send metadata-only snapshots to a central collector.

It never stores prompts, responses, tool arguments, credentials, or raw provider events. Local token counters are usage metadata, not billing records. Read the privacy boundary before sharing a database or report.

Quick start

CLI Consumption requires Python 3.14 or newer and uses uv.

From a checkout, collect every supported CLI detected on the machine and generate a self-contained dashboard:

uv sync
uv run cli-consumption collect --provider all
uv run cli-consumption export --output reports

Open reports/dashboard.html locally. It makes no network requests. Detailed normalized CSV tables are generated only when --csv is passed.

To collect a single CLI, use its provider name. For example, with Codex:

uv run cli-consumption collect --provider codex --database usage.sqlite

From PyPI, no permanent installation is required:

uv tool run cli-consumption collect --provider all
uv tool run cli-consumption export --output reports

To run the latest unreleased GitHub source:

uv tool run --from git+https://github.com/Guillaume-Lombardo/cli-consumption \
  cli-consumption providers

Supported CLIs

--provider all detects the supported data stores found in their default locations. Use the provider name below with --provider to select one CLI explicitly.

Provider formats are internal and can change without notice. The detailed extraction rules and qualification versions are documented in Provider support.

Collect copied data

--source [LABEL=]PATH points to a provider home directory and can be repeated. With --provider all, each path is inspected and unmatched sources are rejected. With one provider selected, each path must contain that provider's expected store.

For example, consolidate trusted copies of Codex data from several machines:

uv run cli-consumption collect --provider codex \
  --source desktop=/data/codex/desktop \
  --source laptop=/data/codex/laptop \
  --source server=/data/codex/server \
  --database usage.sqlite

Copy only the required provider data. For Codex, copy the sessions/ directory but never auth.json or other credentials. Globally identical conversation IDs are deduplicated, and the most complete copy wins.

Map original working-directory prefixes to stable project labels with repeated --project NAME=PATH_PREFIX options. The longest matching prefix wins:

uv run cli-consumption collect --provider codex \
  --source desktop=/data/codex/desktop \
  --project cli-consumption=/home/me/dev/cli-consumption

Plandex auto-detection checks /plandex-server. For any other trusted offline copy of a self-hosted server data directory, pass the path explicitly:

uv run cli-consumption collect --provider plandex \
  --source server=/srv/plandex-server --database usage.sqlite

Explore and share reports

The dashboard can filter by time, provider, machine, project, and model. It reports activity, token composition, cache efficiency, latency and duration distributions, technical throughput, context pressure, work-item reliability, configuration cohorts, compactions, subagent delegation, and ingestion quality. Availability varies by provider, as summarized in the table above.

Generate a more shareable dashboard by pseudonymizing labels, grouping tool names, rounding timestamps to days, and hiding small cohort rows:

uv run cli-consumption export --output shared-report --share-safe

Share-safe reports still disclose aggregate work patterns and remain private operational data. A technically completed turn is not a measure of task quality or productivity.

SQLite and PostgreSQL

A file path selects SQLite. A SQLAlchemy URL selects PostgreSQL:

uv run cli-consumption collect --provider all --database usage.sqlite
uv run cli-consumption collect --provider all \
  --database postgresql+psycopg://usage@localhost/cli_consumption

Pass credentials through environment variables or a secret manager rather than shell history. CLI_CONSUMPTION_DATABASE can provide the database setting.

Central collector API

Copied files are simplest for personal or air-gapped use. For recurring collection across machines, start the metadata-only API:

export CLI_CONSUMPTION_API_TOKEN="$(your-secret-provider)"
uv run cli-consumption serve \
  --database postgresql+psycopg://usage@localhost/cli_consumption \
  --host 0.0.0.0

Then send all locally detected snapshots from another machine:

export CLI_CONSUMPTION_API_TOKEN="$(your-secret-provider)"
uv run cli-consumption sync --provider all \
  --endpoint https://usage.example.test

The application refuses to bind beyond localhost without a token. Production deployments also need TLS and standard operational controls. See Architecture for the trade-offs.

Commands

Run uv run cli-consumption COMMAND --help for all options.

Development

uv sync --all-groups
uv run pre-commit install
uv run pre-commit run --all-files
uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run pytest --cov --cov-report=term-missing
uv build

Development uses short-lived branches and squash-merged pull requests into protected main. Read CONTRIBUTING.md and AGENTS.md before changing the project.

License

Licensed under the Apache License 2.0.