Usage
pflow analyze-cache reads a workflow file (or saved workflow name), finds LLM calls that share static context, and emits recommendations: which values to add to a ## Cache block, which nodes should opt in, and projected cost savings.
It runs in three modes depending on what data it can find:
Inputs are optional. When omitted, token estimates fall back to lower-fidelity sources (memo cache → tokenizer → character heuristic) and the confidence label reflects that. Required inputs that aren’t supplied surface as a single info note rather than blocking the analysis.
Examples
Options
--from-trace and --no-trace-autoload are mutually exclusive. --list-traces
is mutually exclusive with --from-trace, --no-trace-autoload, and
--all-rows; use it as a discovery command, then run analysis with the chosen
trace.
Output
Text output is organized into sections that appear when non-empty:
JSON output (
--format=json) emits the same data with stable field names and format_version for consumer version-gating. See pflow analyze_cache MCP tool for the full schema.
Confidence labels
The header shows an aggregate confidence label based on what data was available:
Per-row counts include their own
data_source so you can tell which rows have real data vs estimates.
Stable warning IDs
Findings carry namespaced IDs (e.g.,cache.shared-context-undeclared, cache.batch-prewarm-recommended, cache.below-min-predicted). The full catalog and what each ID means is in the Prompt caching how-it-works guide.
Exit codes
Warnings never make the command exit non-zero — they’re advisory by design. An agent that wants to gate on findings inspects
warnings[].severity == "error" in the JSON output.
Related
- Prompt caching how-it-works — what the
## Cacheblock does and when to use it - LLM node reference —
prompt_cache:andprewarm:field documentation