CLI usage - GraphRAG

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.

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

Configure models

Specify custom models during initialization:

graphrag init \
  --root ./my-project \
  --model gpt-4o \
  --embedding text-embedding-3-large

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

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

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:

Detects new or modified documents in the input directory
Processes only the changed documents
Merges results with the existing index
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

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

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
Local
DRIFT
Basic

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 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 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 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:

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

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

Initialize project

graphrag init --root ./my-research

Add your documents

cp ~/documents/*.txt ./my-research/input/

Configure API keys

Edit .env and add your API key:

GRAPHRAG_API_KEY=sk-your-key-here

Tune prompts (recommended)

graphrag prompt-tune --root ./my-research --domain "your domain"

Build the index

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

Query your data

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

Incremental updates

Add new documents

cp ~/new-documents/*.txt ./my-research/input/

Update the index

graphrag update --root ./my-research --verbose

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

Get Started

Core Concepts

Indexing

Query Engine

Prompt Tuning

Configuration

Guides

​Installation

​Available commands

init

index

update

prompt-tune

query

​Initialize a project

​Init command options

​Build an index

​Indexing methods

​Index command options

​Update an existing index

​Update command options

​Prompt tuning

​Advanced prompt tuning

​Prompt-tune command options

​Query your index

​Query methods

​Query command options

​Custom response types

​Streaming responses

​Common workflows

​Complete project setup

​Incremental updates

​Troubleshooting

​Check configuration without indexing

​Skip validation for non-LLM steps

​Specify custom data directory

​Next steps

Python API

Configuration

Prompt tuning

Azure setup

Build docs developers (and LLMs) love

Installation

Available commands

Initialize a project

Init command options

Build an index

Indexing methods

Index command options

Update an existing index

Update command options

Prompt tuning

Advanced prompt tuning

Prompt-tune command options

Query your index

Query methods

Query command options

Custom response types

Streaming responses

Common workflows

Complete project setup

Incremental updates

Troubleshooting

Check configuration without indexing

Skip validation for non-LLM steps

Specify custom data directory

Next steps