graphrag-cli

A modern Terminal User Interface (TUI) for GraphRAG operations, built with Ratatui.

Features

• Multi-pane TUI — Results viewer, Raw results, tabbed Info panel (Stats / Sources / History)
• Markdown rendering — LLM answers rendered with bold, italic, headers, bullet points, code blocks
• Three query modes — ASK (fast), EXPLAIN (confidence + sources), REASON (query decomposition)
• Zero-LLM support — Algorithmic pipeline with hash embeddings, no model required
• Vim-style navigation — j/k scrolling, Ctrl+1/2/3/4 focus switching
• Slash command system — /config, /load, /mode, /reason, /export, /workspace, and more
• Query history — Tracked per session, exportable to Markdown
• Workspace persistence — Save/load knowledge graphs to disk
• Direct integration — Uses graphrag-core as a library (no HTTP server needed)

Installation

cd graphrag-rs

# Debug build (fast compile)
cargo build -p graphrag-cli

# Release build (optimized)
cargo build -p graphrag-cli --release

Quick Start — Zero LLM (Symposium example)

Build a knowledge graph from Plato’s Symposium with no LLM required — pure algorithmic extraction using regex patterns, TF-IDF, BM25, and PageRank.

Option A — Interactive TUI

cd /home/dio/graphrag-rs

cargo run -p graphrag-cli -- tui

Then inside the TUI:

/config tests/e2e/configs/algo_hash_medium__symposium.json5
/load docs-example/Symposium.txt
Who is Socrates and what is his role in the Symposium?

Graph builds in ~3-5 seconds. No Ollama needed.

Option B — TUI with config pre-loaded

cargo run -p graphrag-cli -- tui \
  --config tests/e2e/configs/algo_hash_medium__symposium.json5

Then just:

/load docs-example/Symposium.txt
What is Eros according to Aristophanes?

Option C — Benchmark (non-interactive, JSON output)

cargo run -p graphrag-cli -- bench \
  --config tests/e2e/configs/algo_hash_medium__symposium.json5 \
  --book docs-example/Symposium.txt \
  --questions "Who is Socrates?|What is love according to Aristophanes?|What is the Ladder of Beauty?"

Outputs structured JSON with timings, entity counts, answers, confidence scores, and source references.

Available configs

* build ~5s, synthesis ~5-10s per question (with KV cache after the first)

algo_nlp_mistral__symposium.json5 is the recommended config for anyone who wants:

• a graph built quickly with classic NLP methods (no LLM at build time)
• real semantic search with nomic-embed-text
• answers synthesized by Mistral at query time with KV cache enabled

Quick Start — With Ollama (full semantic pipeline)

Requires Ollama running with nomic-embed-text and an LLM (e.g. mistral-nemo:latest).

cargo run -p graphrag-cli -- tui \
  --config tests/e2e/configs/kv_no_gleaning_mistral__symposium.json5

Inside TUI:

/load docs-example/Symposium.txt
/mode explain
How does Diotima describe the ascent to absolute beauty?

The EXPLAIN mode shows confidence score and source references in the Sources tab (Ctrl+4 → Ctrl+N).

CLI Commands

graphrag-cli [OPTIONS] [COMMAND]

Options:
  -c, --config <FILE>      Configuration file to pre-load
  -w, --workspace <NAME>   Workspace name
  -d, --debug              Enable debug logging
      --format <text|json> Output format (default: text)

Commands:
  tui        Start interactive TUI (default)
  setup      Interactive wizard to create a config file
  validate   Validate a configuration file
  bench      Run full E2E benchmark (Init → Load → Query)
  workspace  Manage workspaces (list, create, info, delete)

bench example

cargo run -p graphrag-cli -- bench \
  -c my_config.json5 \
  -b my_document.txt \
  -q "Question 1?|Question 2?|Question 3?"

Output JSON includes: init_ms, build_ms, total_query_ms, entities, relationships, chunks, per-query answer, confidence, sources.

TUI Layout

┌─────────────────────────────────────────────────────────────┐
│  Query Input (Ctrl+1)  (type queries or /commands here)     │
├────────────────────────────────────┬────────────────────────┤
│  Results Viewer (Ctrl+2)           │  Info Panel (Ctrl+4)   │
│  Markdown-rendered LLM answer      │  ┌─Stats─┬─Sources─┬  │
│  with confidence header in EXPLAIN │  │       │History  │  │
│  mode: [EXPLAIN | 85% ████████░░]  │  └───────┴─────────┘  │
├────────────────────────────────────┤  Ctrl+N cycles tabs    │
│  Raw Results (Ctrl+3)              │  (when Info focused)   │
│  Sources list / search results     │                        │
│  before LLM processing             │                        │
└────────────────────────────────────┴────────────────────────┘
│  Status Bar  [mode badge]  ℹ status message                 │
└─────────────────────────────────────────────────────────────┘

Keyboard Shortcuts

Global (IDE-Safe)

Input Box

Scrolling (when viewer focused)

Slash Commands

Query Modes

Switch with /mode <mode> or the badge in the status bar shows the active mode.

One-shot override (doesn’t change sticky mode):

/reason Compare the main arguments of each speaker about love

Architecture

graphrag-cli/src/
├── main.rs                    # CLI entry point (clap)
├── app.rs                     # Main event loop, action routing
├── action.rs                  # Action enum, QueryMode, QueryExplainedPayload
├── commands/mod.rs            # Slash command parser
├── config.rs                  # Config file loading (JSON5/JSON/TOML)
├── theme.rs                   # Dark/light color themes
├── tui.rs                     # Terminal setup/teardown
├── query_history.rs           # Per-session query history
├── workspace.rs               # Workspace metadata management
├── mode.rs                    # Input mode detection
├── handlers/
│   ├── graphrag.rs            # Thread-safe GraphRAG wrapper (Arc<Mutex<>>)
│   ├── bench.rs               # Benchmark runner (JSON output)
│   └── file_ops.rs            # File utilities
└── ui/
    ├── markdown.rs            # Markdown → ratatui Line<'static> parser
    ├── spinner.rs             # Braille spinner animation
    └── components/
        ├── query_input.rs     # Text input widget
        ├── results_viewer.rs  # Markdown-rendered answer + scrollbar
        ├── raw_results_viewer.rs  # Raw search results
        ├── info_panel.rs      # 3-tab panel (Stats/Sources/History)
        ├── status_bar.rs      # Status + query mode badge
        └── help_overlay.rs    # Modal help popup

Technology Stack

• Ratatui 0.29 — TUI framework (immediate mode rendering)
• Crossterm 0.28 — Cross-platform terminal events
• tui-textarea 0.7 — Multi-line input widget
• Tokio 1.32 — Async runtime
• Clap 4.5 — CLI argument parsing
• Dialoguer 0.11 — Interactive setup wizard
• color-eyre 0.6 — Error reporting
• graphrag-core — Knowledge graph engine (direct library call)

License

Same license as the parent graphrag-rs project.