Audit exported token usage against a dated price table you supply. It computes input, output and cache-read charges with integer decimal arithmetic, groups them by workflow and reports budget overruns. It is a local estimate from two documents, not a verified provider bill. Nothing contacts a model, account or pricing service, and nothing writes an output file.
This walkthrough uses the tool's public README and checked-in example files. Run the command from a repository checkout with Node.js 22+.
Run the checked-in example
node bin/llm-cost-ledger.mjs --root examples/clean --usage usage.json --prices prices.json --json
node bin/llm-cost-ledger.mjs --root examples/over-budget --usage usage.json --prices prices.json --json
node bin/llm-cost-ledger.mjs --root examples/unresolved --usage usage.json --prices prices.json --json
npm run checkRead the result
The first exits 0, the second exits 1 (budget-exceeded), and the third exits 2 (price-unresolved). Omit --json for a short human summary on stderr; stdout is always a JSON report except on invalid usage. --help lists every flag. Library callers use auditCosts({ root, usage, prices, limits, now }) and exitCodeFor(report) from src/index.mjs; now is an injected millisecond clock, defaulting to Date.now.
Scope
Each count/byte boundary accepts exactly N and refuses N+1. The time check is injected and cooperative; a single filesystem read, sort or rate lookup can finish before the next checkpoint. Costs stay exact within the declared nonnegative count/rate bounds (one billion tokens per count and one million dollars per million tokens per rate). There is no live API, tokenizer, currency conversion, forecast, billing reconciliation or account action.