Code-Graph-RAG CLI Commands: Complete Guide to `start`, `daemon`, `trace`, `query`, `export`, and `optimize`

Code-Graph-RAG provides six core CLI commands—start, daemon, trace, query, export, and optimize—each registered in codebase_rag/cli.py via Typer and designed for specific graph-based codebase operations.

Code-Graph-RAG (cgr) is an open-source tool that transforms codebases into queryable knowledge graphs. Its command-line interface, built with Typer, serves as the primary entry point for repository analysis, natural-language querying, and automated optimization. This guide covers each Code-Graph-RAG CLI command with implementation details drawn directly from the source code.

The Command Structure

All commands share a common global configuration defined early in codebase_rag/cli.py (lines 104–122). Options like --quiet and --version apply across every subcommand. The CLI delegates specialized operations—daemon management, trace recording, and optimization passes—through a unified router pattern.

start: Launch Interactive Codebase Sessions

The start command initiates a full-stack session: it resolves a repository path, optionally syncs it to Memgraph, and drops you into an interactive chat for natural-language questions.

Implementation Details

• Registration: Line 402 in codebase_rag/cli.py
• Implementation: Lines 408–576

Key Flags

Flag	Purpose
--repo-path	Target repository directory
--update-graph	Force re-sync to Memgraph before chat
--batch-size	Number of Cypher statements per transaction (default: 100)
--no-confirm	Skip interactive prompts

Usage Example

cgr start \
    --repo-path /path/to/project \
    --update-graph \
    --batch-size 200

Once running, the REPL accepts queries like what functions call process_data? and forwards them to main_single_query or main_async in codebase_rag/main.py (lines 1685 and 1699).

daemon: Manage Background Graph Services

The daemon command starts the Memgraph + Qdrant stack that powers all graph-based operations. Without this running, commands like start and export cannot communicate with the knowledge graph.

Implementation Details

• Registration: Line 1004 in codebase_rag/cli.py
• Group invocation: Line 1011

Transport Modes

• stdio (default): Local process communication
• http: Network-accessible API

Usage Example

# Start with default stdio transport

cgr daemon

# Start with HTTP transport for remote access

cgr daemon --transport http

The daemon implementation relies on codebase_rag/mcp/client.py for its MCP (Memory-Cache-Protocol) client functionality.

trace: Record Live Execution Paths

The trace command runs a dedicated sub-CLI for capturing runtime execution traces. These traces are stored in the graph for later analysis of actual code paths versus static dependencies.

Implementation Details

• Registration: Line 1028 in codebase_rag/cli.py
• Entry point: Line 1035
• Sub-CLI location: codebase_rag/trace/cli.py

Usage Example

cgr trace run python my_script.py --repo-path /path/to/project

This records which functions executed during my_script.py and persists those paths to Memgraph, bridging static analysis with dynamic behavior.

query: Natural Language Graph Queries

While there is no standalone query command at the top level, query functionality is embedded within start. When you launch cgr start without --update-graph, it enters query mode immediately. Your natural-language prompts are processed by:

• main_single_query (line 1685, codebase_rag/main.py)
• main_async (line 1699, codebase_rag/main.py)

Interactive Query Example

# Enter query mode (skip re-syncing the graph)

cgr start --repo-path /path/to/project

# Inside the REPL:

> which classes inherit from BaseProcessor?
> find all untested functions in src/api/

The underlying query engine translates these prompts into Cypher queries executed against Memgraph via graph_service.py.

export: Dump Graph Data to JSON

The export command serializes the entire Memgraph knowledge graph to a JSON file for external consumption—backup, migration, or third-party analysis tools.

Implementation Details

• Definition: Line 893 in codebase_rag/cli.py
• Implementation: Lines 894–926

Usage Example

cgr export -o graph.json

The export logic uses codebase_rag/services/graph_service.py as its Memgraph client wrapper, ensuring consistent connection handling with other graph operations.

optimize: Run Codebase Optimization Passes

The optimize command executes language-specific transformation passes—dead-code removal, import pruning, and structural refactoring—then writes improved representations back to Memgraph.

Implementation Details

• Declaration: Line 828 in codebase_rag/cli.py
• Execution: Lines 834–892

Supported Languages and Flags

Parameter	Description
language	Target language (e.g., python, javascript)
--repo-path	Repository to optimize
--reference-document	Architectural guidance document
--orchestrator	LLM for orchestration (e.g., gpt-4o-mini)
--cypher	LLM for Cypher generation

Usage Example

cgr optimize python \
    --repo-path /path/to/project \
    --reference-document docs/architecture.md \
    --orchestrator gpt-4o-mini \
    --cypher gpt-4o-mini

The optimization pipeline delegates to main_optimize_async in codebase_rag/main.py and updates the graph through graph_updater.py.

Additional Management Commands

Beyond the six core commands, the CLI exposes utility subcommands through the same Typer router:

• cgr language — Language-specific tooling
• cgr workspace — Workspace management
• cgr stop — Halt running daemon
• cgr status — Check service health
• cgr doctor — Diagnostic checks
• cgr stats — Repository statistics
• cgr dead-code — Dead code identification
• cgr delete-project — Remove project from graph

Key Source Files Reference

File	Role in CLI
codebase_rag/cli.py	Central Typer definition and command registration
codebase_rag/main.py	Core async entry points: main_single_query, main_async, main_optimize_async
codebase_rag/graph_updater.py	Repository-to-Memgraph synchronization
codebase_rag/services/graph_service.py	Memgraph client wrapper for export, query, optimization
codebase_rag/mcp/client.py	MCP client for daemon communication
codebase_rag/trace/cli.py	trace sub-CLI implementation

Summary

• start launches interactive sessions with optional graph sync (lines 408–576, cli.py)
• daemon manages the Memgraph+Qdrant background stack (line 1004, cli.py)
• trace records live execution via dedicated sub-CLI (line 1028, cli.py; implementation in trace/cli.py)
• query operates through start's REPL, powered by main_single_query/main_async in main.py
• export dumps graphs to JSON using graph_service.py (lines 894–926, cli.py)
• optimize runs transformation passes with LLM orchestration (lines 834–892, cli.py)

All commands respect global flags (--quiet, --version) and support --no-confirm for CI automation.

Frequently Asked Questions

Does Code-Graph-RAG require the daemon to be running?

Yes. The daemon command starts Memgraph and Qdrant services that start, export, and optimize depend on. Without it, you'll encounter connection errors when attempting graph operations. Run cgr daemon before other commands, or check status with cgr status.

How do I query without re-syncing my repository?

Launch cgr start without the --update-graph flag. This skips the graph_updater.py synchronization step and enters the REPL immediately. Your natural-language prompts route directly to main_single_query in main.py against the existing Memgraph data.

Can I automate Code-Graph-RAG in CI pipelines?

Yes. Add --no-confirm to any command to suppress interactive prompts. Combine with --quiet for minimal output. Example: cgr export -o graph.json --no-confirm --quiet runs unattended. Batch operations also benefit from --batch-size tuning for large repositories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}