llm-usage-metrics 0.8.1 → 0.9.0

package/README.md

@@ -29,18 +29,23 @@ The CLI parses session content on your machine. It discovers standard source loc
 
 ## Quick start
 
-Requires Node.js 24 or newer.
+Requires Node.js 22.16+ or 24+ (Node 23 lacks the SQLite busy timeout the ledger uses).
 
 ```bash
 # Run without installing
-npx --yes llm-usage-metrics@latest daily
+npx --yes llm-usage-metrics@latest
 
-# Or install the llm-usage command
+# Or install it: the package provides `llm-usage` and the alias `llm-usage-metrics`
 npm install -g llm-usage-metrics
-llm-usage daily
+llm-usage
+
+# Optional: tab completion (bash shown; zsh and fish work the same way)
+echo 'source <(llm-usage completion bash)' >> ~/.bashrc
 ```
 
-If the report is empty, check source discovery:
+With no command, `llm-usage` prints cost and tokens for today, the last 7 days, and month to date, a month-end projection (checked against `monthlyBudgetUsd` when you set one), what prompt caching saved you this month, then your current and longest streak, best day, and a year-long activity heatmap. `llm-usage daily` breaks the last 7 days down by day and source, and `llm-usage weekly` covers the last 8 weeks; add `--since YYYY-MM-DD` or `--all` for older usage.
+
+If the report is empty, check source discovery. `doctor` lists the paths each source searched and marks it found, not installed, or unparseable:
 
 ```bash
 llm-usage doctor
@@ -50,6 +55,7 @@ llm-usage doctor
 
 | Question                                                  | Command                                   |
 | --------------------------------------------------------- | ----------------------------------------- |
+| What did I spend today, this week, and this month?        | `llm-usage`                               |
 | How much did I use by day, week, or month?                | `llm-usage daily`, `weekly`, `monthly`    |
 | How did one period change from another?                   | `llm-usage compare`                       |
 | Which conversations or repositories used the most?        | `llm-usage session`                       |
@@ -57,6 +63,7 @@ llm-usage doctor
 | How does repo-attributed usage line up with Git activity? | `llm-usage efficiency monthly`            |
 | What would the same token mix cost on another model?      | `llm-usage optimize monthly`              |
 | What did the year add up to?                              | `llm-usage wrapped`                       |
+| What can my status bar show?                              | `llm-usage statusline`                    |
 | How do I get the raw normalized events out?               | `llm-usage events`                        |
 | Which sources and local stores are healthy?               | `llm-usage doctor`                        |
 | Which departed files can leave the event ledger?          | `llm-usage prune`                         |
@@ -69,7 +76,7 @@ Common examples:
 # A chosen calendar range
 llm-usage monthly --since 2026-06-01 --until 2026-06-30
 
-# Current local month compared with the previous month
+# Current month to date compared with the same days of the previous month
 llm-usage compare
 
 # Ten highest-cost conversations
@@ -87,6 +94,9 @@ llm-usage optimize monthly \
   --candidate-model gpt-4.1 \
   --candidate-model gpt-5-codex
 
+# One line for the Claude Code status line, tmux, or starship
+llm-usage statusline
+
 # Normalized events as JSONL, e.g. total tokens per line via jq
 llm-usage events --since 2026-06-01 | jq '.totalTokens'
 ```
@@ -157,10 +167,10 @@ The pricing request never includes session content. See [Pricing](https://ayagma
 
 ## Local event ledger
 
-A SQLite event ledger stores normalized events and parse diagnostics. Unchanged files can skip parsing on later runs. The ledger also supports retained history for files that have left the disk:
+A SQLite event ledger stores normalized events and parse diagnostics. Unchanged files can skip parsing on later runs. Reports also include retained history for files that have left the disk (Claude Code, for example, deletes old transcripts), with moved or copied files suppressed. Leave it out with `--no-history`:
 
 ```bash
-llm-usage monthly --history
+llm-usage monthly --no-history
 ```
 
 `prune` is a dry run unless you pass `--apply`:
@@ -175,14 +185,17 @@ Deleting the ledger also deletes retained history. Read [Caching](https://ayagma
 ## Output
 
 ```bash
-llm-usage daily --json
+llm-usage daily --all --json
 llm-usage daily --markdown
+llm-usage daily --compact
 llm-usage monthly --share
 ```
 
-Report data goes to `stdout`. Discovery, pricing, config, and skipped-row diagnostics go to `stderr`, which keeps JSON and Markdown safe to redirect. JSON output is wrapped in a versioned envelope: `{ "schemaVersion": 1, "report": "usage", "data": ... }`. Scripts written against pre-0.8.0 JSON should follow the [migration guide](https://ayagmar.github.io/llm-usage-metrics/migrating-to-0-8/).
+Terminal tables fit the terminal width: on a narrow terminal, token counts are abbreviated and less-used columns are hidden, with a `stderr` note saying what was left out. `--compact` asks for the short table directly.
 
-Terminal, JSON, and Markdown availability varies by report. Usage, trends, wrapped, efficiency, and optimize can write supported share SVGs. The [output guide](https://ayagmar.github.io/llm-usage-metrics/output-formats/) contains the format matrix and file names.
+Report data goes to `stdout`. Diagnostics go to `stderr` as one summary line plus any warnings, which keeps JSON and Markdown safe to redirect; `--quiet` keeps only warnings and `--verbose` adds per-source and skipped-row detail. JSON output is wrapped in a versioned envelope: `{ "schemaVersion": 1, "report": "usage", "data": ... }`. Scripts written against pre-0.8.0 JSON should follow the [migration guide](https://ayagmar.github.io/llm-usage-metrics/migrating-to-0-8/).
+
+Terminal, JSON, and Markdown availability varies by report. Summary, usage, compare, trends, wrapped, efficiency, and optimize can write a 1200×630 share card: an SVG plus an HTML page that shows it in dark and light and exports a PNG in your browser. `--share --no-open` writes the files without opening the page. The [output guide](https://ayagmar.github.io/llm-usage-metrics/output-formats/) contains the format matrix and file names.
 
 ## Performance
 
@@ -201,9 +214,12 @@ pnpm run format:check
 pnpm run build
 ```
 
+The website has a [docs overview](https://ayagmar.github.io/llm-usage-metrics/docs/) and a [report chooser](https://ayagmar.github.io/llm-usage-metrics/reports/) for finding the right command. Its landing page and source navigation use the CLI source registry; regenerate CLI and security references after behavior changes.
+
 Site commands:
 
 ```bash
+pnpm run site:docs:generate
 pnpm run site:check
 pnpm run site:build
 pnpm run site:dev