Repository navigation
[Feature Request] Add cache-first mode to skip "Refreshing model pricing from LiteLLM..." delay #1627
Description
What happened?
Every time I run ccusage, it gets stuck at the Refreshing model pricing from LiteLLM... status for a very long time during startup. For users who only care about quickly checking the token usage for the current session and don't really care about real-time pricing updates, this waiting time feels unnecessary and hurts the user experience.
I would like to request a parameter (e.g., --cache-only or --fast) that allows the program to use locally cached pricing data directly, skipping the online refresh process entirely, and just output the token counts quickly. Additionally, a separate command (e.g., ccusage update-prices) could be provided to manually update the price cache when needed.
Steps to reproduce
Run ccusage (or any command that includes token statistics) in the terminal;
The program displays Refreshing model pricing from LiteLLM... at startup;
It takes a long time before proceeding to the actual token usage output;
If the network is unstable or the LiteLLM service is slow to respond, the wait time becomes even longer.
Expected behavior
Add a --cache-only or --fast flag. When this flag is used, the program should only read from the local price cache and not make any external API requests;
Add a standalone command ccusage update-prices to manually refresh the price cache;
The cache could have a TTL (e.g., 24 hours). When expired, the program could prompt the user to run the update command, or simply proceed with a warning at the user's discretion;
In --cache-only mode, even if the cache is expired, the program should still use it and display a notice like "Using cached pricing data, may be outdated".
Version
20.0.20
Activity
pullfrog commentedon Aug 22, 2026
Assessment
This issue is actionable as a follow-up enhancement, but the first requested behavior is already available in a narrower form.
--offlineskips the runtime LiteLLM refresh and uses the embedded LiteLLM/models.dev snapshots. It does not use a persisted runtime pricing cache, and the repository has no end-userccusage update-pricescommand. The issue is currently auto-closed, so it would need to be reopened by a maintainer before implementation.Proposed Plan
--offlineas the deterministic embedded-snapshot mode. Add a separately named cache-only mode, recommended as--cache-only, that never performs network I/O, uses the persisted pricing documents even when stale, warns when stale, and falls back to embedded pricing with a clear warning when no valid cache exists. Decide and document the cache location, TTL/staleness threshold, cache format, and whether cache-only applies to statusline pricing as well as reports.ccusage-corecontinues to own parsing and pricing precedence. Cache the LiteLLM document and the models.dev document separately, validate successful responses before replacing cache files, and use atomic writes. Keep the existing online path as network-first and refresh the cache after successful fetches; use a bounded timeout and preserve the existing embedded fallback on network or parse failure.ccusage update-pricescommand. It should fetch and validate each supported pricing source, update the cache only for successful sources, report what was updated, and return a failure status if an update cannot be completed without discarding an existing cache. Ensure it does not load usage logs or trigger the normal report pricing flow.--offline/--no-offlinebehavior.update-pricessuccess and failure reporting. Add HTTP tests for response validation and cache writes without introducing a mock HTTP dependency, following the existing standard-library listener pattern.README.md,apps/ccusage/README.md, the pricing/offline section ofdocs/guide/config-files.md, statusline guidance if applicable, and generated schema/help artifacts. Explain the distinction between embedded--offline, persisted--cache-only, normal online refresh, cache staleness warnings, andccusage update-prices.just fmt,just test, andjust checkrecipes plus documentation/schema validation. Confirm that a cache-only invocation makes no external request and that the worktree is clean before opening the implementation PR.Task list (3/3 completed)
@v0or keep the SHA fresh with Dependabot ｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ UsingGPT Luna(free via Pullfrog for OSS) ｜ 𝕏github-actions commentedon Aug 22, 2026
This issue was auto-closed. Issues from new contributors are auto-closed by default.
Maintainers review auto-closed issues and reopen worthwhile ones. Issues that do not meet the quality bar in CONTRIBUTING.md may not be reopened or receive a reply.
Keep the issue short, concrete, and written in your own voice.
If a maintainer replies
lgtmi, your future issues will stay open. If a maintainer replieslgtm, your future issues and PRs will stay open.See CONTRIBUTING.md.
ryoppippi commentedon Aug 31, 2026
Historical audit: this discussion was auto-closed by the legacy contributor gate. That closure did not assess technical importance.
Audit result: maintainable candidate. The request fits the current ccusage scope and can be evaluated with repository-owned code or fixtures, without vendor credentials or platform-specific release infrastructure. It remains closed for now; reopen only after confirming current relevance and expected behavior.