CLI Reference

rag-doctor <command> [options] <input>

rag-doctor analyze <trace-file> [options]
 
Options:
  --json          Output findings as structured JSON
  --config <path> Path to a .rag-doctor.json config file
  --pack <name>   Rule pack to use: recommended (default) | strict | minimal
  --quiet         Suppress informational output, show only findings
  --verbose       Show full chunk content in findings
 
Examples:
  rag-doctor analyze trace.json
  rag-doctor analyze trace.json --json
  rag-doctor analyze trace.json --config .rag-doctor.json --json
  rag-doctor analyze trace.json --pack strict

Analyzing trace: trace.json
Running rule pack: recommended (4 rules)
 
  ⚠  duplicate-chunks
     2 near-identical chunks detected (similarity: 0.94 > threshold: 0.85)
     Affected: chunk-002, chunk-005
 
  ✗  low-retrieval-score
     Chunk score below minimum threshold (0.41 < 0.72)
     Affected: chunk-003
 
  ⚠  context-overload
     Context window at 94% capacity (3,820 / 4,096 tokens)
 
─────────────────────────────────────
3 findings  ·  1 critical  ·  2 warnings

1{
2  "ok": false,
3  "findings": [
4    {
5      "rule": "duplicate-chunks",
6      "severity": "warning",
7      "message": "2 near-identical chunks detected (similarity: 0.94)",
8      "evidence": {
9        "pairs": [["chunk-002", "chunk-005"]],
10        "similarity": 0.94,
11        "threshold": 0.85
12      }
13    },
14    {
15      "rule": "low-retrieval-score",
16      "severity": "error",
17      "message": "Chunk score below minimum threshold",
18      "evidence": {
19        "chunkId": "chunk-003",
20        "score": 0.41,
21        "threshold": 0.72
22      }
23    },
24    {
25      "rule": "context-overload",
26      "severity": "warning",
27      "message": "Context window at 94% capacity",
28      "evidence": {
29        "totalTokens": 3820,
30        "limit": 4096,
31        "utilizationPct": 93.3
32      }
33    }
34  ],
35  "summary": {
36    "total": 3,
37    "critical": 1,
38    "warnings": 2,
39    "passed": 1
40  }
41}

rag-doctor diagnose <trace-file> [options]
 
Options:
  --json          Output diagnosis as structured JSON
  --config <path> Path to config file
 
Examples:
  rag-doctor diagnose trace.json
  rag-doctor diagnose trace.json --json
  rag-doctor diagnose trace.json --json | jq '.diagnosis.primaryCause'

1{
2  "ok": false,
3  "findings": [ ...3 findings... ],
4  "diagnosis": {
5    "primaryCause": {
6      "id": "low-retrieval-score",
7      "label": "Poor retrieval quality",
8      "description": "The retrieval step is returning chunks with relevance scores below the acceptable threshold. This is the most likely root cause of downstream hallucination or incorrect answers.",
9      "severity": "critical"
10    },
11    "contributingCauses": [
12      {
13        "id": "duplicate-chunks",
14        "label": "Duplicate context",
15        "description": "Near-identical chunks are consuming context space without adding information diversity."
16      }
17    ],
18    "recommendations": [
19      "Review your embedding model and index — low scores often indicate embedding mismatch",
20      "Consider re-ranking retrieved chunks before passing to the LLM",
21      "Increase the retrieval score threshold to filter out low-quality results",
22      "Deduplicate your document corpus or increase chunk diversity in retrieval"
23    ]
24  }
25}

rag-doctor --help
rag-doctor analyze --help
rag-doctor diagnose --help