CLI usage

Learn how to use GraphRAG’s command-line interface for indexing and querying knowledge graphs

The GraphRAG CLI provides a comprehensive set of commands for initializing projects, building knowledge graph indexes, and querying your data. All commands are accessible through the graphrag command.

Installation

Ensure GraphRAG is installed before using the CLI:

pip install graphrag

Available commands

The GraphRAG CLI includes five main commands:

init

Generate a default configuration file

index

Build a knowledge graph index

update

Update an existing index

prompt-tune

Generate custom prompts from your data

query

Query a knowledge graph index

Initialize a project

The init command creates a new GraphRAG project with default configuration files.

1. Run initialization

   graphrag init --root ./my-project
   

   This creates:

   • settings.yaml - Configuration file
   • .env - Environment variables for API keys
   • prompts/ - Directory with default prompt templates
   • input/ - Directory for source documents
2. Configure models

   Specify custom models during initialization:

   graphrag init \
     --root ./my-project \
     --model gpt-4o \
     --embedding text-embedding-3-large
   
3. Force overwrite (optional)

   Use --force to overwrite existing configuration:

   graphrag init --root ./my-project --force
   

   The --force flag will overwrite your existing settings.yaml and prompts. Back up your customizations first.

Init command options

Option	Short	Description	Default
--root	-r	Project root directory	Current directory
--model	-m	Default chat model to use	gpt-4-turbo-preview
--embedding	-e	Default embedding model	text-embedding-3-small
--force	-f	Force initialization even if project exists	false

Build an index

The index command processes your documents and builds a knowledge graph.

graphrag index --root ./my-project

Indexing methods

Standard (default)

graphrag index --root ./my-project --method standard

graphrag index --root ./my-project --verbose

graphrag index --root ./my-project --dry-run

graphrag index --root ./my-project --no-cache

Index command options

Option	Short	Description	Default
--root	-r	Project root directory	Current directory
--method	-m	Indexing method to use	standard
--verbose	-v	Enable verbose logging	false
--dry-run		Validate config without executing	false
--cache/--no-cache		Enable/disable LLM cache	true
--skip-validation		Skip preflight validation	false

Use --dry-run to validate your configuration before running a full index. This helps catch configuration errors early.

Update an existing index

The update command incrementally updates an existing index with new documents.

graphrag update --root ./my-project

The update process:

1. Detects new or modified documents in the input directory
2. Processes only the changed documents
3. Merges results with the existing index
4. Outputs to update_output/ folder by default

Always run graphrag init --force between minor version bumps to ensure you have the latest config format before updating.

Update command options

Option	Short	Description	Default
--root	-r	Project root directory	Current directory
--method	-m	Indexing method to use	standard
--verbose	-v	Enable verbose logging	false
--cache/--no-cache		Enable/disable LLM cache	true
--skip-validation		Skip preflight validation	false

Prompt tuning

The prompt-tune command generates custom prompts tailored to your data domain.

graphrag prompt-tune --root ./my-project

Advanced prompt tuning

With domain specification

graphrag prompt-tune \
  --root ./my-project \
  --domain "medical research"

graphrag prompt-tune \
  --root ./my-project \
  --selection-method auto \
  --n-subset-max 300 \
  --k 15

graphrag prompt-tune \
  --root ./my-project \
  --output ./custom-prompts

graphrag prompt-tune \
  --root ./my-project \
  --language "Spanish"

Prompt-tune command options

Option	Description	Default
--root	Project root directory	Current directory
--domain	Domain of your input data	Auto-detected
--selection-method	Text chunk selection method (random, top, auto)	random
--n-subset-max	Number of chunks to embed (auto mode)	300
--k	Max documents per centroid (auto mode)	15
--limit	Number of documents to load (random/top)	15
--max-tokens	Max token count for prompt generation	2000
--chunk-size	Size of each text chunk	200
--language	Primary language for prompts	Auto-detected
--output	Directory to save prompts	prompts

Use --selection-method auto for large datasets. It uses k-means clustering to select representative documents.

Query your index

The query command searches your knowledge graph index.

graphrag query "What are the main themes in the dataset?" \
  --root ./my-project \
  --method global

Query methods

GraphRAG supports four search methods:

Global

Global search uses the entire knowledge graph to answer questions about the dataset as a whole.

graphrag query "What are the main themes?" \
  --method global \
  --community-level 2

Best for: High-level questions, dataset summaries, theme identification

Local

Local search focuses on specific entities and their relationships.

graphrag query "Tell me about John Smith" \
  --method local \
  --community-level 2

Best for: Specific entity queries, detailed information retrieval

DRIFT

DRIFT combines local and global approaches for comprehensive answers.

graphrag query "How do the themes relate to specific people?" \
  --method drift \
  --community-level 2

Best for: Complex queries requiring both breadth and depth

Basic

Basic search uses simple text similarity without the knowledge graph.

graphrag query "Find mentions of AI" \
  --method basic

Best for: Simple keyword searches, quick lookups

Query command options

Option	Short	Description	Default
query		The query string (required)	-
--root	-r	Project root directory	Current directory
--method	-m	Query algorithm (global, local, drift, basic)	global
--data	-d	Index output directory	Auto-detected
--community-level		Leiden hierarchy level	2
--dynamic-community-selection		Use dynamic community selection	false
--response-type		Desired response format	Multiple Paragraphs
--streaming		Stream the response	false
--verbose	-v	Enable verbose logging	false

Custom response types

You can specify different response formats:

Single sentence

graphrag query "What is this about?" \
  --response-type "Single Sentence"

graphrag query "List the main findings" \
  --response-type "List of 3-7 Points"

graphrag query "Explain the methodology" \
  --response-type "Multiple Paragraphs"

Streaming responses

Enable streaming for real-time output:

graphrag query "Complex research question" \
  --method global \
  --streaming

Use --streaming for long-form responses to see results as they’re generated.

Common workflows

Complete project setup

1. Initialize project

   graphrag init --root ./my-research
   
2. Add your documents

   cp ~/documents/*.txt ./my-research/input/
   
3. Configure API keys

   Edit .env and add your API key:

   GRAPHRAG_API_KEY=sk-your-key-here
   
4. Tune prompts (recommended)

   graphrag prompt-tune --root ./my-research --domain "your domain"
   
5. Build the index

   graphrag index --root ./my-research --verbose
   
6. Query your data

   graphrag query "What are the main findings?" \
     --root ./my-research \
     --method global
   

Incremental updates

1. Add new documents

   cp ~/new-documents/*.txt ./my-research/input/
   
2. Update the index

   graphrag update --root ./my-research --verbose
   
3. Query updated index

   Point queries to the update output:

   graphrag query "What's new?" \
     --root ./my-research \
     --data ./my-research/update_output
   

Troubleshooting

Check configuration without indexing

graphrag index --root ./my-project --dry-run --verbose

Skip validation for non-LLM steps

graphrag index --root ./my-project --skip-validation

Specify custom data directory

graphrag query "my question" \
  --data ./custom/output/path

Next steps

Python API

Learn how to use GraphRAG programmatically

Configuration

Customize your GraphRAG settings

Prompt tuning

Optimize prompts for your domain

Azure setup

Configure Azure OpenAI integration