cli-consumption 0.2.1__tar.gz → 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. cli_consumption-0.3.1/CHANGELOG.md +122 -0
  2. cli_consumption-0.3.1/PKG-INFO +198 -0
  3. cli_consumption-0.3.1/README.md +161 -0
  4. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/pyproject.toml +36 -5
  5. cli_consumption-0.3.1/src/cli_consumption/adapters/_shared.py +421 -0
  6. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/aider.py +21 -17
  7. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/amazon_q.py +16 -12
  8. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/amp.py +29 -41
  9. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/claude.py +24 -31
  10. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/cline.py +27 -16
  11. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/codex.py +32 -18
  12. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/continue_cli.py +26 -21
  13. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/copilot.py +20 -18
  14. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/crush.py +69 -76
  15. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/cursor.py +20 -15
  16. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/gemini.py +33 -43
  17. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/goose.py +66 -71
  18. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/grok.py +28 -25
  19. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/kilo.py +65 -74
  20. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/kimi.py +8 -4
  21. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/mistral_vibe.py +10 -5
  22. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/opencode.py +50 -68
  23. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/openhands.py +34 -45
  24. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/pi.py +29 -48
  25. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/plandex.py +11 -5
  26. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/qwen.py +24 -34
  27. cli_consumption-0.3.1/src/cli_consumption/adapters/registry.py +475 -0
  28. cli_consumption-0.3.1/src/cli_consumption/api.py +484 -0
  29. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/cli.py +250 -27
  30. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/dashboard.py +587 -253
  31. cli_consumption-0.3.1/src/cli_consumption/dashboard_calculations.js +543 -0
  32. cli_consumption-0.3.1/src/cli_consumption/exporting.py +117 -0
  33. cli_consumption-0.3.1/src/cli_consumption/migrations/versions/v0004_subagent_scope_freshness.py +38 -0
  34. cli_consumption-0.3.1/src/cli_consumption/migrations/versions/v0005_sync_receipts.py +38 -0
  35. cli_consumption-0.3.1/src/cli_consumption/qualifications.py +97 -0
  36. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/reporting.py +76 -1
  37. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/schema.py +116 -12
  38. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/storage.py +229 -90
  39. cli_consumption-0.3.1/src/cli_consumption/sync.py +169 -0
  40. cli_consumption-0.2.1/.agents/skills/add-cli-adapter/SKILL.md +0 -21
  41. cli_consumption-0.2.1/.agents/skills/add-cli-adapter/agents/openai.yaml +0 -4
  42. cli_consumption-0.2.1/.agents/skills/audit-usage-privacy/SKILL.md +0 -22
  43. cli_consumption-0.2.1/.agents/skills/audit-usage-privacy/agents/openai.yaml +0 -4
  44. cli_consumption-0.2.1/.agents/skills/evolve-storage-schema/SKILL.md +0 -21
  45. cli_consumption-0.2.1/.agents/skills/evolve-storage-schema/agents/openai.yaml +0 -4
  46. cli_consumption-0.2.1/.agents/skills/yeet-github/SKILL.md +0 -66
  47. cli_consumption-0.2.1/.agents/skills/yeet-github/agents/openai.yaml +0 -4
  48. cli_consumption-0.2.1/.agents/skills/yolo/SKILL.md +0 -50
  49. cli_consumption-0.2.1/.agents/skills/yolo/agents/openai.yaml +0 -4
  50. cli_consumption-0.2.1/.github/workflows/ci.yml +0 -64
  51. cli_consumption-0.2.1/.github/workflows/release.yaml +0 -154
  52. cli_consumption-0.2.1/.pre-commit-config.yaml +0 -35
  53. cli_consumption-0.2.1/.python-version +0 -1
  54. cli_consumption-0.2.1/AGENTS.md +0 -68
  55. cli_consumption-0.2.1/CONTRIBUTING.md +0 -56
  56. cli_consumption-0.2.1/PKG-INFO +0 -323
  57. cli_consumption-0.2.1/README.md +0 -288
  58. cli_consumption-0.2.1/SECURITY.md +0 -37
  59. cli_consumption-0.2.1/docs/architecture.md +0 -124
  60. cli_consumption-0.2.1/docs/decisions/0001-versioned-schema-migrations.md +0 -50
  61. cli_consumption-0.2.1/docs/decisions/0002-canonical-utc-timestamps.md +0 -94
  62. cli_consumption-0.2.1/docs/privacy.md +0 -106
  63. cli_consumption-0.2.1/docs/provider-support.md +0 -422
  64. cli_consumption-0.2.1/docs/roadmap.md +0 -33
  65. cli_consumption-0.2.1/src/cli_consumption/adapters/_shared.py +0 -180
  66. cli_consumption-0.2.1/src/cli_consumption/adapters/registry.py +0 -250
  67. cli_consumption-0.2.1/src/cli_consumption/api.py +0 -143
  68. cli_consumption-0.2.1/src/cli_consumption/exporting.py +0 -55
  69. cli_consumption-0.2.1/src/cli_consumption/sync.py +0 -80
  70. cli_consumption-0.2.1/tests/conftest.py +0 -133
  71. cli_consumption-0.2.1/tests/smoke_minimal_install.py +0 -69
  72. cli_consumption-0.2.1/tests/test_aider_adapter.py +0 -204
  73. cli_consumption-0.2.1/tests/test_amazon_q_adapter.py +0 -67
  74. cli_consumption-0.2.1/tests/test_amp_adapter.py +0 -257
  75. cli_consumption-0.2.1/tests/test_api.py +0 -164
  76. cli_consumption-0.2.1/tests/test_claude_adapter.py +0 -218
  77. cli_consumption-0.2.1/tests/test_cli.py +0 -1171
  78. cli_consumption-0.2.1/tests/test_cline_adapter.py +0 -102
  79. cli_consumption-0.2.1/tests/test_codex_adapter.py +0 -256
  80. cli_consumption-0.2.1/tests/test_continue_adapter.py +0 -266
  81. cli_consumption-0.2.1/tests/test_copilot_adapter.py +0 -348
  82. cli_consumption-0.2.1/tests/test_crush_adapter.py +0 -304
  83. cli_consumption-0.2.1/tests/test_cursor_adapter.py +0 -230
  84. cli_consumption-0.2.1/tests/test_exporting.py +0 -85
  85. cli_consumption-0.2.1/tests/test_gemini_adapter.py +0 -275
  86. cli_consumption-0.2.1/tests/test_goose_adapter.py +0 -269
  87. cli_consumption-0.2.1/tests/test_grok_adapter.py +0 -304
  88. cli_consumption-0.2.1/tests/test_input_limits.py +0 -57
  89. cli_consumption-0.2.1/tests/test_kilo_adapter.py +0 -292
  90. cli_consumption-0.2.1/tests/test_kimi_adapter.py +0 -82
  91. cli_consumption-0.2.1/tests/test_migrations_and_retention.py +0 -752
  92. cli_consumption-0.2.1/tests/test_mistral_vibe_adapter.py +0 -207
  93. cli_consumption-0.2.1/tests/test_opencode_adapter.py +0 -261
  94. cli_consumption-0.2.1/tests/test_openhands_adapter.py +0 -313
  95. cli_consumption-0.2.1/tests/test_packaging.py +0 -26
  96. cli_consumption-0.2.1/tests/test_pi_adapter.py +0 -287
  97. cli_consumption-0.2.1/tests/test_plandex_adapter.py +0 -68
  98. cli_consumption-0.2.1/tests/test_provider_registry.py +0 -191
  99. cli_consumption-0.2.1/tests/test_qwen_adapter.py +0 -295
  100. cli_consumption-0.2.1/tests/test_reporting.py +0 -248
  101. cli_consumption-0.2.1/tests/test_snapshot_contract.py +0 -75
  102. cli_consumption-0.2.1/tests/test_storage_and_exports.py +0 -342
  103. cli_consumption-0.2.1/tests/test_sync.py +0 -104
  104. cli_consumption-0.2.1/tests/test_timestamps.py +0 -61
  105. cli_consumption-0.2.1/uv.lock +0 -987
  106. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/.gitignore +0 -0
  107. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/LICENSE +0 -0
  108. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/NOTICE +0 -0
  109. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/__init__.py +0 -0
  110. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/__main__.py +0 -0
  111. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/__init__.py +0 -0
  112. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/adapters/base.py +0 -0
  113. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/migrations/__init__.py +0 -0
  114. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/migrations/env.py +0 -0
  115. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/migrations/versions/__init__.py +0 -0
  116. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/migrations/versions/v0001_baseline.py +0 -0
  117. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/migrations/versions/v0002_minimize_subagents.py +0 -0
  118. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/migrations/versions/v0003_canonical_timestamps.py +0 -0
  119. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/models.py +0 -0
  120. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/py.typed +0 -0
  121. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/retention.py +0 -0
  122. {cli_consumption-0.2.1 → cli_consumption-0.3.1}/src/cli_consumption/timestamps.py +0 -0
@@ -0,0 +1,122 @@
1
+ # Changelog
2
+
3
+ Notable user-visible changes to CLI Consumption are documented in this file. The
4
+ format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases
5
+ use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.3.1] - 2026-08-31
10
+
11
+ ### Changed
12
+
13
+ - Python 3.11 is now supported and tested alongside Python 3.12, 3.13, and 3.14.
14
+ - Collection errors now distinguish provider limits, incompatible formats, invalid
15
+ snapshots, and unexpected adapter failures with privacy-safe human messages and
16
+ deterministic JSON codes.
17
+ - A pinned, privacy-preserving single-host production deployment example now covers
18
+ the central collector, PostgreSQL, and automatic TLS proxy operations.
19
+ - The README now leads with a reproducible synthetic dashboard preview and routes
20
+ operational and provider-qualification detail to dedicated guides.
21
+ - CI now performs scheduled Python security, locked dependency, and offline workflow
22
+ audits; third-party actions are pinned to immutable commits with least privileges.
23
+ - Provider adapters now carry auditable format qualification metadata backed by
24
+ synthetic fixtures, with a weekly check that flags qualifications older than 90
25
+ days and homogeneous privacy-minimized compatibility criteria.
26
+ - Linear is now the source of truth for new repository tasks and their progress, while
27
+ the roadmap remains focused on durable product direction.
28
+ - Dashboard token totals now include conversation aggregates and latest-context
29
+ snapshots for conversations overlapping the selected period, with explicit labels
30
+ distinguishing them from additive usage.
31
+ - Dashboard selection, period, aggregation, percentile, and comparison calculations
32
+ now use an independently tested JavaScript contract embedded in the offline report.
33
+ - Each detailed CSV export now uses a synchronized temporary file and atomic
34
+ replacement, preserving that table's previous file when generation fails early.
35
+ - Multi-provider sync now reuses one HTTP client, negotiates capabilities once, and
36
+ performs bounded idempotent retries when the collector advertises replay receipts.
37
+ - Sync automation now supports strict preflight refusal and deterministic JSON with
38
+ malformed/duplicate diagnostics, explicit partial success, and generic remote
39
+ errors that do not expose response or provider content.
40
+
41
+ ### Fixed
42
+
43
+ - Reject timezone-naive provider timestamps instead of interpreting them in the host
44
+ timezone.
45
+
46
+ ## [0.3.0] - 2026-08-29
47
+
48
+ ### Added
49
+
50
+ - Added privacy-safe database readiness checks and bounded request correlation for the
51
+ collector service ([#35]).
52
+
53
+ ### Changed
54
+
55
+ - Provider input processing now enforces cumulative discovery, byte, SQLite row, and
56
+ structured-field limits across a complete collection ([#31]).
57
+ - Dashboard generation now preflights bounded selections, streams its output, and
58
+ atomically replaces an existing report only after a successful write ([#32]).
59
+ - Concurrent schema initialization, upgrade, and downgrade are now serialized on
60
+ SQLite and PostgreSQL, with SQLite lock waits capped at 15 seconds ([#34]).
61
+ - Published source distributions exclude repository-only tests and automation while
62
+ retaining release metadata, the changelog and README, license notices, the runtime
63
+ package, and Hatchling's rebuild `.gitignore` ([#33]).
64
+ - Identical adapter primitives are shared while provider-specific parsing semantics
65
+ remain isolated ([#36]).
66
+
67
+ ### Fixed
68
+
69
+ - Older, identical, graph-only, and partially stale snapshots can no longer erase a
70
+ newer subagent relationship graph ([#30]).
71
+
72
+ ## [0.2.1] - 2026-08-29
73
+
74
+ ### Changed
75
+
76
+ - Hardened ingestion privacy and normalized persisted timestamps to canonical,
77
+ fixed-width UTC values ([#29]).
78
+
79
+ ## [0.2.0] - 2026-08-29
80
+
81
+ ### Added
82
+
83
+ - Added versioned SQLite and PostgreSQL schema migrations, retention previews, and a
84
+ metadata-only central collector and synchronization client ([#28]).
85
+ - Added streamed CSV exports, time-window selection, and a share-safe dashboard
86
+ profile ([#28]).
87
+
88
+ ### Changed
89
+
90
+ - Strengthened snapshot validation, transport defaults, storage deduplication, and
91
+ privacy regression coverage ([#28]).
92
+
93
+ ## [0.1.1] - 2026-08-27
94
+
95
+ ### Added
96
+
97
+ - Added the Mistral Vibe CLI adapter ([#27]).
98
+
99
+ ## [0.1.0] - 2026-08-27
100
+
101
+ ### Changed
102
+
103
+ - Refreshed the provider guide for the first minor release ([#26]).
104
+
105
+ [Unreleased]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.3.1...HEAD
106
+ [0.3.1]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.3.0...v0.3.1
107
+ [0.3.0]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.2.1...v0.3.0
108
+ [0.2.1]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.2.0...v0.2.1
109
+ [0.2.0]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.1.1...v0.2.0
110
+ [0.1.1]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.1.0...v0.1.1
111
+ [0.1.0]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.0.18...v0.1.0
112
+ [#26]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/26
113
+ [#27]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/27
114
+ [#28]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/28
115
+ [#29]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/29
116
+ [#30]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/30
117
+ [#31]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/31
118
+ [#32]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/32
119
+ [#33]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/33
120
+ [#34]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/34
121
+ [#35]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/35
122
+ [#36]: https://github.com/Guillaume-Lombardo/cli-consumption/pull/36
@@ -0,0 +1,198 @@
1
+ Metadata-Version: 2.5
2
+ Name: cli-consumption
3
+ Version: 0.3.1
4
+ Summary: Analyze and consolidate AI coding CLI consumption across machines.
5
+ Project-URL: Homepage, https://github.com/Guillaume-Lombardo/cli-consumption
6
+ Project-URL: Documentation, https://github.com/Guillaume-Lombardo/cli-consumption#readme
7
+ Project-URL: Changelog, https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CHANGELOG.md
8
+ Project-URL: Issues, https://github.com/Guillaume-Lombardo/cli-consumption/issues
9
+ Project-URL: Repository, https://github.com/Guillaume-Lombardo/cli-consumption.git
10
+ Author-email: Guillaume Lombardo <lombardo.guillaume@gmail.com>
11
+ License-Expression: Apache-2.0
12
+ License-File: LICENSE
13
+ License-File: NOTICE
14
+ Keywords: ai,cli,codex,observability,tokens,usage
15
+ Classifier: Development Status :: 3 - Alpha
16
+ Classifier: Environment :: Console
17
+ Classifier: License :: OSI Approved :: Apache Software License
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Software Development :: Quality Assurance
24
+ Requires-Python: >=3.11
25
+ Requires-Dist: alembic>=1.14
26
+ Requires-Dist: pydantic>=2.10
27
+ Requires-Dist: sqlalchemy>=2.0
28
+ Requires-Dist: typer>=0.15
29
+ Provides-Extra: postgres
30
+ Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
31
+ Provides-Extra: server
32
+ Requires-Dist: fastapi>=0.115; extra == 'server'
33
+ Requires-Dist: uvicorn>=0.34; extra == 'server'
34
+ Provides-Extra: sync
35
+ Requires-Dist: httpx>=0.27; extra == 'sync'
36
+ Description-Content-Type: text/markdown
37
+
38
+ # CLI Consumption
39
+
40
+ CLI Consumption turns local AI coding CLI metadata into one private, self-contained
41
+ view of models, tokens, tools, conversations, turns, context pressure, and workflow
42
+ health. It can consolidate trusted offline copies from several machines or send
43
+ metadata-only snapshots to a central collector.
44
+
45
+ It never stores prompts, responses, tool arguments, credentials, or raw provider
46
+ events. Local token counters are usage metadata, not billing records. Read the
47
+ [privacy boundary](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
48
+ before sharing a database or report.
49
+
50
+ [![Synthetic CLI Consumption dashboard](https://raw.githubusercontent.com/Guillaume-Lombardo/cli-consumption/main/docs/demo/dashboard.png)](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/demo/dashboard.html)
51
+
52
+ The preview and
53
+ [self-contained demo dashboard](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/demo/dashboard.html)
54
+ contain only
55
+ deterministic synthetic records. Rebuild the HTML with:
56
+
57
+ ```bash
58
+ uv run python docs/demo/generate.py
59
+ ```
60
+
61
+ The generator never reads provider directories and creates its temporary SQLite
62
+ database outside the repository. The demo HTML, image, documentation, tests, and other
63
+ repository assets are excluded from Python distribution artifacts.
64
+
65
+ ## Installation
66
+
67
+ CLI Consumption requires Python 3.11 or newer. Run it directly from PyPI with `uv`:
68
+
69
+ ```bash
70
+ uv tool run cli-consumption providers
71
+ ```
72
+
73
+ The default package covers local collection, SQLite storage, and exports. Install only
74
+ the optional runtime capabilities you use:
75
+
76
+ - `cli-consumption[sync]` for the sync client;
77
+ - `cli-consumption[server]` for the collector service;
78
+ - `cli-consumption[postgres]` for PostgreSQL.
79
+
80
+ Extras can be combined, for example `cli-consumption[server,postgres]` on a central
81
+ collector.
82
+
83
+ ## Quick start
84
+
85
+ From a checkout, detect supported local CLIs, collect their metadata, and create an
86
+ offline dashboard:
87
+
88
+ ```bash
89
+ uv sync --all-extras
90
+ uv run cli-consumption collect --provider all
91
+ uv run cli-consumption export --output reports
92
+ ```
93
+
94
+ Open `reports/dashboard.html` locally. It makes no network requests. Detailed CSV
95
+ tables are generated only when `--csv` is passed.
96
+
97
+ To collect one provider or select another database:
98
+
99
+ ```bash
100
+ uv run cli-consumption collect --provider codex --database usage.sqlite
101
+ ```
102
+
103
+ Use `--source [LABEL=]PATH` for trusted offline copies and repeated
104
+ `--project NAME=PATH_PREFIX` mappings for stable project labels. See the
105
+ [usage and operations guide](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
106
+ for multi-machine collection, reporting,
107
+ PostgreSQL, retention, synchronization, readiness, and automation.
108
+
109
+ ## Supported CLIs
110
+
111
+ The current registry supports Aider, Amazon Q Developer CLI, Amp, Claude Code, Cline,
112
+ Codex, Continue, Crush, Cursor CLI, Gemini CLI, GitHub Copilot CLI, Goose, Grok Build,
113
+ Kilo Code, Kimi Code CLI, Mistral Vibe CLI, OpenCode, OpenHands CLI, Pi, Plandex, and
114
+ Qwen Code.
115
+
116
+ Provider formats are internal and can change without notice. Exact source locations,
117
+ token semantics, extraction limits, synthetic qualification fixtures, provenance, and
118
+ known gaps live in the
119
+ [provider support ledger](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/provider-support.md).
120
+ Inspect the
121
+ local registry without exposing paths or content:
122
+
123
+ ```bash
124
+ uv run cli-consumption providers --json
125
+ ```
126
+
127
+ ## Essential limits
128
+
129
+ - Provider files are untrusted. Collection enforces discovery, file, line, SQLite row,
130
+ structured-field, and total normalized-record limits; direct provider-file symlinks
131
+ are refused.
132
+ - `collect --strict` and `sync --strict` refuse a batch when any provider skipped
133
+ malformed records. Collection distinguishes `provider_limit_exceeded`,
134
+ `provider_format_incompatible`, `invalid_snapshot`, and the unexpected-failure
135
+ fallback `provider_collection_failed`; machine-readable results use these fixed codes
136
+ without paths, payloads, response bodies, tokens, or exception text.
137
+ - Dashboards are self-contained and network-free. Share-safe mode pseudonymizes
138
+ labels, groups tools, rounds timestamps, and hides small cohorts, but still exposes
139
+ aggregate work patterns.
140
+ - CSV and normalized databases remain detailed private operational data. Never treat a
141
+ technically completed turn as a measure of quality or productivity.
142
+ - Central collection requires TLS, token rotation, backups, limits, monitoring, and a
143
+ reverse proxy. The application does not replace those operator controls.
144
+
145
+ See [Privacy](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
146
+ for the exact data boundary and
147
+ [Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md)
148
+ for ingestion, idempotency, migrations, report limits, and collector behavior.
149
+
150
+ ## Commands
151
+
152
+ | Command | Purpose |
153
+ | --- | --- |
154
+ | `collect` | Collect local or copied provider data into SQL. |
155
+ | `sync` | Collect and send metadata-only snapshots to a central API. |
156
+ | `serve` | Run the central collection API. |
157
+ | `export` | Write the HTML dashboard and optional CSV tables. |
158
+ | `providers` | List provider names and compatibility status. |
159
+ | `retention` | Preview or apply deletion outside a retention window. |
160
+
161
+ Run `uv run cli-consumption COMMAND --help` for every option. The
162
+ [usage guide](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
163
+ contains copy-ready examples.
164
+
165
+ ## Documentation
166
+
167
+ - [Usage and operations](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
168
+ - [Production deployment](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/deployment.md)
169
+ - [Provider support and qualification](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/provider-support.md)
170
+ - [Privacy boundary](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
171
+ - [Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md)
172
+ - [Roadmap](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/roadmap.md)
173
+ - [Contributing](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CONTRIBUTING.md)
174
+ - [Security policy](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/SECURITY.md)
175
+
176
+ ## Development
177
+
178
+ ```bash
179
+ uv sync --all-extras --all-groups
180
+ uv run pre-commit install
181
+ uv run pre-commit run --all-files
182
+ uv run ruff format --check .
183
+ uv run ruff check .
184
+ uv run ty check
185
+ uv run pytest --cov --cov-report=term-missing
186
+ uv build
187
+ ```
188
+
189
+ Development uses short-lived branches and squash-merged pull requests into protected
190
+ `main`. Read
191
+ [CONTRIBUTING.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CONTRIBUTING.md)
192
+ and [AGENTS.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/AGENTS.md)
193
+ before changing the project.
194
+
195
+ ## License
196
+
197
+ Licensed under the
198
+ [Apache License 2.0](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/LICENSE).
@@ -0,0 +1,161 @@
1
+ # CLI Consumption
2
+
3
+ CLI Consumption turns local AI coding CLI metadata into one private, self-contained
4
+ view of models, tokens, tools, conversations, turns, context pressure, and workflow
5
+ health. It can consolidate trusted offline copies from several machines or send
6
+ metadata-only snapshots to a central collector.
7
+
8
+ It never stores prompts, responses, tool arguments, credentials, or raw provider
9
+ events. Local token counters are usage metadata, not billing records. Read the
10
+ [privacy boundary](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
11
+ before sharing a database or report.
12
+
13
+ [![Synthetic CLI Consumption dashboard](https://raw.githubusercontent.com/Guillaume-Lombardo/cli-consumption/main/docs/demo/dashboard.png)](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/demo/dashboard.html)
14
+
15
+ The preview and
16
+ [self-contained demo dashboard](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/demo/dashboard.html)
17
+ contain only
18
+ deterministic synthetic records. Rebuild the HTML with:
19
+
20
+ ```bash
21
+ uv run python docs/demo/generate.py
22
+ ```
23
+
24
+ The generator never reads provider directories and creates its temporary SQLite
25
+ database outside the repository. The demo HTML, image, documentation, tests, and other
26
+ repository assets are excluded from Python distribution artifacts.
27
+
28
+ ## Installation
29
+
30
+ CLI Consumption requires Python 3.11 or newer. Run it directly from PyPI with `uv`:
31
+
32
+ ```bash
33
+ uv tool run cli-consumption providers
34
+ ```
35
+
36
+ The default package covers local collection, SQLite storage, and exports. Install only
37
+ the optional runtime capabilities you use:
38
+
39
+ - `cli-consumption[sync]` for the sync client;
40
+ - `cli-consumption[server]` for the collector service;
41
+ - `cli-consumption[postgres]` for PostgreSQL.
42
+
43
+ Extras can be combined, for example `cli-consumption[server,postgres]` on a central
44
+ collector.
45
+
46
+ ## Quick start
47
+
48
+ From a checkout, detect supported local CLIs, collect their metadata, and create an
49
+ offline dashboard:
50
+
51
+ ```bash
52
+ uv sync --all-extras
53
+ uv run cli-consumption collect --provider all
54
+ uv run cli-consumption export --output reports
55
+ ```
56
+
57
+ Open `reports/dashboard.html` locally. It makes no network requests. Detailed CSV
58
+ tables are generated only when `--csv` is passed.
59
+
60
+ To collect one provider or select another database:
61
+
62
+ ```bash
63
+ uv run cli-consumption collect --provider codex --database usage.sqlite
64
+ ```
65
+
66
+ Use `--source [LABEL=]PATH` for trusted offline copies and repeated
67
+ `--project NAME=PATH_PREFIX` mappings for stable project labels. See the
68
+ [usage and operations guide](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
69
+ for multi-machine collection, reporting,
70
+ PostgreSQL, retention, synchronization, readiness, and automation.
71
+
72
+ ## Supported CLIs
73
+
74
+ The current registry supports Aider, Amazon Q Developer CLI, Amp, Claude Code, Cline,
75
+ Codex, Continue, Crush, Cursor CLI, Gemini CLI, GitHub Copilot CLI, Goose, Grok Build,
76
+ Kilo Code, Kimi Code CLI, Mistral Vibe CLI, OpenCode, OpenHands CLI, Pi, Plandex, and
77
+ Qwen Code.
78
+
79
+ Provider formats are internal and can change without notice. Exact source locations,
80
+ token semantics, extraction limits, synthetic qualification fixtures, provenance, and
81
+ known gaps live in the
82
+ [provider support ledger](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/provider-support.md).
83
+ Inspect the
84
+ local registry without exposing paths or content:
85
+
86
+ ```bash
87
+ uv run cli-consumption providers --json
88
+ ```
89
+
90
+ ## Essential limits
91
+
92
+ - Provider files are untrusted. Collection enforces discovery, file, line, SQLite row,
93
+ structured-field, and total normalized-record limits; direct provider-file symlinks
94
+ are refused.
95
+ - `collect --strict` and `sync --strict` refuse a batch when any provider skipped
96
+ malformed records. Collection distinguishes `provider_limit_exceeded`,
97
+ `provider_format_incompatible`, `invalid_snapshot`, and the unexpected-failure
98
+ fallback `provider_collection_failed`; machine-readable results use these fixed codes
99
+ without paths, payloads, response bodies, tokens, or exception text.
100
+ - Dashboards are self-contained and network-free. Share-safe mode pseudonymizes
101
+ labels, groups tools, rounds timestamps, and hides small cohorts, but still exposes
102
+ aggregate work patterns.
103
+ - CSV and normalized databases remain detailed private operational data. Never treat a
104
+ technically completed turn as a measure of quality or productivity.
105
+ - Central collection requires TLS, token rotation, backups, limits, monitoring, and a
106
+ reverse proxy. The application does not replace those operator controls.
107
+
108
+ See [Privacy](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
109
+ for the exact data boundary and
110
+ [Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md)
111
+ for ingestion, idempotency, migrations, report limits, and collector behavior.
112
+
113
+ ## Commands
114
+
115
+ | Command | Purpose |
116
+ | --- | --- |
117
+ | `collect` | Collect local or copied provider data into SQL. |
118
+ | `sync` | Collect and send metadata-only snapshots to a central API. |
119
+ | `serve` | Run the central collection API. |
120
+ | `export` | Write the HTML dashboard and optional CSV tables. |
121
+ | `providers` | List provider names and compatibility status. |
122
+ | `retention` | Preview or apply deletion outside a retention window. |
123
+
124
+ Run `uv run cli-consumption COMMAND --help` for every option. The
125
+ [usage guide](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
126
+ contains copy-ready examples.
127
+
128
+ ## Documentation
129
+
130
+ - [Usage and operations](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
131
+ - [Production deployment](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/deployment.md)
132
+ - [Provider support and qualification](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/provider-support.md)
133
+ - [Privacy boundary](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
134
+ - [Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md)
135
+ - [Roadmap](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/roadmap.md)
136
+ - [Contributing](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CONTRIBUTING.md)
137
+ - [Security policy](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/SECURITY.md)
138
+
139
+ ## Development
140
+
141
+ ```bash
142
+ uv sync --all-extras --all-groups
143
+ uv run pre-commit install
144
+ uv run pre-commit run --all-files
145
+ uv run ruff format --check .
146
+ uv run ruff check .
147
+ uv run ty check
148
+ uv run pytest --cov --cov-report=term-missing
149
+ uv build
150
+ ```
151
+
152
+ Development uses short-lived branches and squash-merged pull requests into protected
153
+ `main`. Read
154
+ [CONTRIBUTING.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CONTRIBUTING.md)
155
+ and [AGENTS.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/AGENTS.md)
156
+ before changing the project.
157
+
158
+ ## License
159
+
160
+ Licensed under the
161
+ [Apache License 2.0](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/LICENSE).
@@ -4,11 +4,12 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "cli-consumption"
7
- version = "0.2.1"
7
+ version = "0.3.1"
8
8
  description = "Analyze and consolidate AI coding CLI consumption across machines."
9
9
  readme = "README.md"
10
- requires-python = ">=3.12"
10
+ requires-python = ">=3.11"
11
11
  license = "Apache-2.0"
12
+ license-files = ["LICENSE", "NOTICE"]
12
13
  authors = [{ name = "Guillaume Lombardo", email = "lombardo.guillaume@gmail.com" }]
13
14
  keywords = ["ai", "cli", "codex", "observability", "tokens", "usage"]
14
15
  classifiers = [
@@ -16,6 +17,7 @@ classifiers = [
16
17
  "Environment :: Console",
17
18
  "License :: OSI Approved :: Apache Software License",
18
19
  "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.11",
19
21
  "Programming Language :: Python :: 3.12",
20
22
  "Programming Language :: Python :: 3.13",
21
23
  "Programming Language :: Python :: 3.14",
@@ -36,6 +38,7 @@ sync = ["httpx>=0.27"]
36
38
  [project.urls]
37
39
  Homepage = "https://github.com/Guillaume-Lombardo/cli-consumption"
38
40
  Documentation = "https://github.com/Guillaume-Lombardo/cli-consumption#readme"
41
+ Changelog = "https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CHANGELOG.md"
39
42
  Issues = "https://github.com/Guillaume-Lombardo/cli-consumption/issues"
40
43
  Repository = "https://github.com/Guillaume-Lombardo/cli-consumption.git"
41
44
 
@@ -46,6 +49,8 @@ cli-consumption = "cli_consumption.cli:app"
46
49
  dev = [
47
50
  "fastapi>=0.115",
48
51
  "httpx>=0.27",
52
+ "hypothesis>=6.165.10",
53
+ "pip-audit>=2.10.1",
49
54
  "pre-commit>=4.6.2",
50
55
  "psycopg[binary]>=3.2",
51
56
  "pytest>=8.3",
@@ -53,11 +58,23 @@ dev = [
53
58
  "ruff>=0.11",
54
59
  "ty>=0.0.74",
55
60
  "uvicorn>=0.34",
61
+ "zizmor>=1.29.0",
56
62
  ]
57
63
 
58
64
  [tool.hatch.build.targets.wheel]
59
65
  packages = ["src/cli_consumption"]
60
66
 
67
+ [tool.hatch.build.targets.sdist]
68
+ include = [
69
+ "/LICENSE",
70
+ "/NOTICE",
71
+ "/CHANGELOG.md",
72
+ "/README.md",
73
+ "/pyproject.toml",
74
+ "/src/cli_consumption",
75
+ ]
76
+ exclude = ["**/__pycache__", "**/*.pyc"]
77
+
61
78
  [tool.pytest.ini_options]
62
79
  addopts = "--strict-config --strict-markers"
63
80
  testpaths = ["tests"]
@@ -72,10 +89,24 @@ show_missing = true
72
89
 
73
90
  [tool.ruff]
74
91
  line-length = 88
75
- target-version = "py312"
92
+ target-version = "py311"
76
93
 
77
94
  [tool.ruff.lint]
78
- select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
95
+ select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "S"]
79
96
 
80
97
  [tool.ruff.lint.per-file-ignores]
81
- "src/cli_consumption/dashboard.py" = ["E501"]
98
+ "src/cli_consumption/adapters/_shared.py" = ["S608"]
99
+ "src/cli_consumption/adapters/cline.py" = ["S608"]
100
+ "src/cli_consumption/adapters/crush.py" = ["S608"]
101
+ "src/cli_consumption/adapters/kilo.py" = ["S608"]
102
+ "src/cli_consumption/adapters/opencode.py" = ["S608"]
103
+ "src/cli_consumption/adapters/registry.py" = ["S105", "S106"]
104
+ "src/cli_consumption/api.py" = ["S608"]
105
+ "src/cli_consumption/cli.py" = ["S107"]
106
+ "src/cli_consumption/dashboard.py" = ["E501", "S608"]
107
+ "tests/**" = ["S101"]
108
+ "tests/smoke_minimal_install.py" = ["S603", "S607"]
109
+ "tests/test_codex_adapter.py" = ["S608"]
110
+ "tests/test_dashboard_calculations.py" = ["S607"]
111
+ "tests/test_demo.py" = ["S603"]
112
+ "tests/test_packaging.py" = ["S603", "S607"]