llm-usage-metrics 0.1.5 → 0.1.7

package/README.md

@@ -104,12 +104,24 @@ llm-usage monthly --pricing-offline
 llm-usage monthly --pricing-url https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
 ```
 
+Pricing behavior notes:
+
+- LiteLLM is the active pricing source.
+- explicit `costUsd: 0` events are re-priced from LiteLLM when model pricing is available.
+- when pricing cannot be loaded from LiteLLM (or cache in offline mode), report generation fails fast.
+
 ### Custom session directories
 
 ```bash
 llm-usage daily --pi-dir /path/to/pi/sessions --codex-dir /path/to/codex/sessions
 ```
 
+Or use generic source-id mapping (repeatable):
+
+```bash
+llm-usage daily --source-dir pi=/path/to/pi/sessions --source-dir codex=/path/to/codex/sessions
+```
+
 ### Filter by source
 
 Only codex rows:
@@ -131,7 +143,78 @@ llm-usage monthly --source pi --source codex
 llm-usage monthly --source pi,codex
 ```
 
-## Output semantics
+### Filter by provider (optional)
+
+```bash
+llm-usage monthly --provider openai
+llm-usage monthly --provider github
+llm-usage monthly --provider kimi
+```
+
+### Filter by model (optional)
+
+`--model` supports repeatable/comma-separated filters. Matching is case-insensitive.
+
+- if an exact model exists for a filter value, exact matching is used
+- otherwise, substring matching is used
+
+```bash
+# substring match (all Claude-family models)
+llm-usage monthly --model claude
+
+# exact match when present
+llm-usage monthly --model claude-sonnet-4.5
+
+# multiple filters
+llm-usage monthly --model claude --model gpt-5
+llm-usage monthly --model claude,gpt-5
+```
+
+### Per-model columns (opt-in detailed table layout)
+
+Default output is compact (model names only in the Models column).
+
+Use `--per-model-columns` to render per-model multiline metrics in each numeric column:
+
+```bash
+llm-usage monthly --per-model-columns
+llm-usage monthly --markdown --per-model-columns
+```
+
+## Output features
+
+### Terminal UI
+
+The CLI provides an enhanced terminal output with:
+
+- **Boxed report header** showing the report type and timezone
+- **Session summary** displayed at startup (session files and event counts per source)
+- **Pricing source info** indicating whether data was loaded from cache or fetched remotely
+- **Environment variable overrides** displayed when active
+- **Models displayed as bullet points** for better readability
+- **Rounded table borders** and improved color scheme
+
+Example output:
+
+```text
+ℹ Found 12 session file(s) with 45 event(s)
+•   pi: 8 file(s), 32 events
+•   codex: 4 file(s), 13 events
+ℹ Loaded pricing from cache
+
+┌──────────────────────────────────────────────────────────┐
+│ Monthly Token Usage Report (Timezone: Africa/Casablanca) │
+└──────────────────────────────────────────────────────────┘
+
+╭────────────┬──────────┬──────────────────────╮
+│ Period     │ Source   │ Models               │
+├────────────┼──────────┼──────────────────────┤
+│ Feb 2026   │ pi       │ • gpt-5.2            │
+│            │          │ • gpt-5.2-codex      │
+╰────────────┴──────────┴──────────────────────╯
+```
+
+### Report structure
 
 Each report includes:
 
@@ -149,8 +232,8 @@ Columns:
 - Reasoning
 - Cache Read
 - Cache Write
-- Total Tokens
-- Cost (USD)
+- Total
+- Cost
 
 ## Development