Skip to main content

​
Usage

pflow analyze-cache <WORKFLOW> [PARAMS...]
pflow analyze-cache <WORKFLOW> [PARAMS...] --format=json
pflow analyze-cache <WORKFLOW> --from-trace <TRACE_PATH>
pflow analyze-cache <WORKFLOW> --list-traces
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:
ModeTriggers whenOutput emphasis
GreenfieldWorkflow has no ## Cache blockDetection + paste-ready suggested block
Steady-stateWorkflow has ## Cache declaredPer-chunk usage, validation, padding advisories
Trace-drivenA 2.x trace was loaded (auto or --from-trace)Predicted vs actual cache ratios with root-cause attribution
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

# Analyze a workflow file (auto-loads matching trace from ~/.pflow/debug/)
pflow analyze-cache ./song-creator.pflow.md

# Skip auto-load, analyze fresh
pflow analyze-cache ./song-creator.pflow.md --no-trace-autoload

# Compare predicted to actual using an explicit trace
pflow analyze-cache ./song-creator.pflow.md \
  --from-trace ~/.pflow/debug/workflow-trace-abc12345-song-creator-20260507.json

# List matching traces and the trace that auto-load would pick
pflow analyze-cache ./song-creator.pflow.md --list-traces

# JSON output for agent consumption
pflow analyze-cache ./song-creator.pflow.md --format=json

# Show every node, not just rows with warnings or low cache ratios
pflow analyze-cache ./song-creator.pflow.md --all-rows

​
Options

FlagDefaultDescription
--format=text|jsontextHuman-readable text or stable JSON for agents
--from-trace <path>-Explicit trace file (any 2.x format). Overrides auto-load
--no-trace-autoloadoffSkip the most-recent matching trace from ~/.pflow/debug/
--all-rowsoffShow every LLM node in the per-call table; default hides clean rows
--list-tracesoffList matching traces and exit without running analysis
--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:
SectionWhat it shows
HeaderWorkflow path, scale (LLM call count, models in use), confidence label
SummaryCurrent cost per run, projected cost with caching, projected rerun cost (within TTL)
Recommended actionsNumbered (ordered by impact when at least one action has a positive savings figure; unordered when no model is resolved or all savings are unavailable). Each item carries a stable warning ID and the edit to apply.
Suggested ## Cache blockPaste-ready block for greenfield mode, with starter prose for each chunk
Sub-workflow boundariesCross-file findings: rename detection, prose mismatches, value-flow opportunities
Per-call cache reportTable of LLM nodes with model, input tokens, cached-now tokens, ready tokens, upside tokens, ratio, confidence
NotesPer-invocation scoping notes, mixed-model context, fallback hints
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:
LabelMeaning
high_from_traceToken counts read from a runtime trace — actual numbers
medium_from_memoToken counts from prior runs via the memo cache
low_no_dataToken counts estimated from the prompt template via tokenizer
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

CodeMeaning
0Analysis succeeded (warnings still surface in output)
1Workflow couldn’t be parsed or resolved
2Invalid flag combination (e.g., --from-trace + --no-trace-autoload)
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.