Metadata-Version: 2.5
Name: cli-consumption
Version: 0.0.1
Summary: Analyze and consolidate AI coding CLI consumption across machines.
Project-URL: Homepage, https://github.com/Guillaume-Lombardo/cli-consumption
Project-URL: Documentation, https://github.com/Guillaume-Lombardo/cli-consumption#readme
Project-URL: Issues, https://github.com/Guillaume-Lombardo/cli-consumption/issues
Project-URL: Repository, https://github.com/Guillaume-Lombardo/cli-consumption.git
Author-email: Guillaume Lombardo <lombardo.guillaume@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai,cli,codex,observability,tokens,usage
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.14
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: psycopg[binary]>=3.2
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: typer>=0.15
Requires-Dist: uvicorn>=0.34
Description-Content-Type: text/markdown

# CLI Consumption

CLI Consumption is a local-first Python package for measuring how AI coding CLIs use
models, tokens, tools, conversations, and turns. It can analyze one workstation,
consolidate copied data from several machines, or send metadata-only snapshots to a
central collector.

Codex is fully supported. Claude Code, OpenCode, Kilo Code, and Pi are planned behind
the same provider-neutral adapter contract.

The collector deliberately excludes prompts, responses, tool arguments, and
credentials. See [Privacy](docs/privacy.md) before sharing a database or export.

## Quick start

The project requires Python 3.14 or newer and uses
[`uv`](https://docs.astral.sh/uv/) for every development and execution workflow.

From a checkout:

```bash
uv sync
uv run cli-consumption collect
uv run cli-consumption export --output reports
```

Open `reports/dashboard.html` locally. The generated dashboard is self-contained and
makes no network requests.

The dashboard supports time, provider, machine, project, and model filters. It reports
period-over-period activity, token composition, cache efficiency, turn latency and
duration distributions, technical throughput, context pressure, content-free work-item
duration and reliability, configuration cohorts, compactions, subagent delegation, and
ingestion quality. Token events are local usage metadata rather than billing records,
and a technically completed turn is not a measure of task quality or productivity.

For a dashboard that is safer to share, omit the detailed CSV exports, pseudonymize
machine, project, model, and role labels, group tool names, round timestamps to days,
and hide small rows in the cohort-comparison view:

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

Share-safe reports still disclose aggregate work patterns and must be treated as
private operational data.

From PyPI, the CLI can run without a permanent installation:

```bash
uv tool run cli-consumption collect
uv tool run cli-consumption export --output reports
```

To run the latest unreleased GitHub source instead:

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

## Collect from one or more machines

With no source option, `collect` reads `~/.codex` and labels it with the local
hostname:

```bash
uv run cli-consumption collect --database usage.sqlite
```

For an offline multi-machine workflow, copy only each machine's Codex `sessions/`
directory into a trusted analysis location. Do not copy `auth.json` or other
credentials. Then repeat `--source`:

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

Globally identical conversation IDs are deduplicated. If copies differ, the most
complete rollout wins. Explicit project mappings use the longest matching original
working-directory prefix:

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

## SQLite and PostgreSQL

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

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

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

## Central collector API

Offline imports are the simplest choice for personal use and air-gapped machines. A
central API is useful for recurring collection across machines.

Start the collector locally:

```bash
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
```

Send a snapshot from another machine:

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

The application refuses to bind beyond localhost without a token. Production
deployments must also place TLS and normal operational controls in front of the ASGI
server. See [Architecture](docs/architecture.md) for trade-offs.

## Commands

```text
cli-consumption collect    Collect local or copied provider data into SQL
cli-consumption sync       Collect and send a snapshot to a central API
cli-consumption serve      Run the central collection API
cli-consumption export     Write CSV tables and the HTML dashboard
cli-consumption providers  Show supported and planned providers
```

Run `uv run cli-consumption COMMAND --help` for every option.

## Development

```bash
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 follows short-lived branches and squash-merged pull requests into a
protected `main`. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md)
before changing the project.

## License

Licensed under the [Apache License 2.0](LICENSE). It provides permissive reuse plus an
explicit patent grant and contribution protections appropriate for an extensible
developer tool.
