# How to Start an Interactive Query Session with Code-Graph-RAG: A Complete CLI Guide > Learn to start an interactive query session with Code-Graph-RAG using the CLI. Follow this guide to launch the natural-language-to-Cypher REPL and explore your codebase efficiently. - Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag) - Tags: how-to-guide - Published: 2026-09-05 --- **Start an interactive query session by running `cgr start --repo-path ` (add `--update-graph` for first-time indexing) to launch the natural-language-to-Cypher REPL defined in [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py).** The **Code-Graph-RAG** project (repository `vitali87/code-graph-rag`) transforms natural language questions into executable Cypher queries against a Memgraph knowledge graph. Its command-line interface provides an interactive REPL environment where you can explore, query, and edit your codebase using plain English instead of complex graph syntax. ## CLI Entry Point and Command Structure The executable **`cgr`** serves as the primary interface, forwarding commands to [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py) where the `start` subcommand is defined. When you invoke `cgr start`, the CLI initializes an application context and checks whether stdin is interactive via `_stdin_is_interactive` before proceeding. The actual interactive loop lives in **[`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py)** within the `_run_interactive_loop` async function. This architecture separates argument parsing (handled in [`cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/cli.py)) from session orchestration (handled in [`main.py`](https://github.com/vitali87/code-graph-rag/blob/main/main.py)), ensuring clean separation between CLI concerns and the REPL implementation. ## Prerequisites and Initial Setup Before launching a session, ensure your infrastructure is ready: 1. **Memgraph instance** must be running (start with `cgr daemon up`) 2. **Repository path** accessible on your local filesystem 3. **Python environment** with Code-Graph-RAG installed (`pipx install "code-graph-rag[treesitter-full,semantic]"`) If this is your first time indexing the target repository, you must include the `--update-graph` flag to parse the codebase and populate the knowledge graph. ## Starting Your First Interactive Session To begin exploring a codebase immediately, execute the start command with your repository path: ```bash # First-time setup: parse and index the repository cgr start --repo-path /path/to/your/project --update-graph ``` For subsequent sessions where the graph is already current, omit the rebuild flag for faster startup: ```bash # Fast startup using existing graph index cgr start --repo-path /path/to/your/project ``` The CLI creates a per-session log file via `init_session_log` and launches the prompt toolkit interface, presenting you with a `>` prompt ready to accept natural language queries. ## How the Interactive Loop Works Once initiated, `_run_interactive_loop` manages the conversation flow between you and the codebase knowledge graph. ### Session Initialization The loop creates a **`PromptSession`** using the *prompt_toolkit* library, providing line-editing capabilities and history management. It initializes the **agentic context** that exposes tools like `query_graph`, `read_file`, and `replace_code` to the LLM orchestrator. ### Query Processing Pipeline For each user input, the session executes this sequence: 1. **Natural Language Parsing** – The input routes through `create_rag_orchestrator`, which delegates to `CypherGenerator` to translate English into executable Cypher queries 2. **Graph Execution** – The generated Cypher runs against Memgraph via `MemgraphIngestor` 3. **Result Rendering** – The **rich** library formats results in the terminal, displaying node relationships and code references 4. **Action Availability** – The system offers follow-up actions including viewing source code or editing files directly This pipeline continues until you explicitly terminate the session. ## Available CLI Options The `cgr start` command accepts several flags to control indexing behavior: - **`--repo-path `** – Required. Points to the root directory of the source tree you wish to query - **`--update-graph`** – Optional but recommended for first runs. Triggers parsing of the entire codebase to build or refresh the knowledge graph - **`--clean`** – Optional. Clears prior graph data before indexing; prompts for confirmation unless you also pass `-y` to force ## Navigating and Exiting the Session While inside the interactive loop, type natural language questions exactly as you would ask a colleague. For example: "Find all functions that call the authentication module" or "Show me the inheritance hierarchy of the BaseHandler class". To terminate the session: - Press **Ctrl-D** (sends EOF signal) - Type **`exit`** at the prompt Both methods gracefully close the `PromptSession` and return control to your shell. ## Summary - **`cgr start`** launches the interactive REPL defined in [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py) and [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py) - Use **`--repo-path`** to specify your target codebase and **`--update-graph`** for initial indexing - The **`_run_interactive_loop`** function manages the session using *prompt_toolkit* and orchestrates queries through `create_rag_orchestrator` - Results render via the **rich** library, with support for viewing and editing source code through built-in agentic tools - Exit anytime with **Ctrl-D** or the **`exit`** command ## Frequently Asked Questions ### Do I need to rebuild the graph every time I start a session? No. The `--update-graph` flag is only required when you want to parse new changes or are indexing the repository for the first time. According to the [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py) implementation, omitting this flag skips the parsing phase and connects directly to the existing Memgraph database, significantly reducing startup time for subsequent sessions. ### What happens if I press Ctrl-D during a query? Pressing **Ctrl-D** sends an EOF signal that the `_run_interactive_loop` interprets as a shutdown command. Unlike interrupting with Ctrl-C (which might abort the current operation), Ctrl-D triggers a clean exit sequence that closes the `PromptSession` and releases database connections without corrupting session logs or leaving orphaned transactions in Memgraph. ### Can I use Code-Graph-RAG without an existing Memgraph instance? No. The interactive session requires a running Memgraph database to execute the Cypher queries generated by `CypherGenerator`. If you attempt to start a session without the database running, the `MemgraphIngestor` component will fail to establish a connection. Always verify your instance is active using `cgr daemon up` before invoking `cgr start`. ### Where are the agentic tools defined that power the interactive queries? The agentic tools—such as `query_graph` for executing searches, `read_file` for displaying source code, and `replace_code` for modifications—are implemented in the `codebase_rag/tools/` directory. These tools are exposed to the LLM during the `_run_interactive_loop` session, allowing the system to augment natural language responses with real-time graph access and file system operations as documented in [`docs/guide/interactive-querying.md`](https://github.com/vitali87/code-graph-rag/blob/main/docs/guide/interactive-querying.md).