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

> Master Code-Graph-RAG CLI commands start daemon trace query export and optimize for efficient codebase analysis. Explore this complete guide to unlock graph-based operations.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Code-Graph-RAG provides six core CLI commands—`start`, `daemon`, `trace`, `query`, `export`, and `optimize`—each registered in [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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

```bash
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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py)
- **Group invocation**: Line 1011

### Transport Modes

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

### Usage Example

```bash

# 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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py)
- **Entry point**: Line 1035
- **Sub-CLI location**: [`codebase_rag/trace/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/trace/cli.py)

### Usage Example

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

```

This records which functions executed during [`my_script.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py))
- `main_async` (line 1699, [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py))

### Interactive Query Example

```bash

# 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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py)
- **Implementation**: Lines 894–926

### Usage Example

```bash
cgr export -o graph.json

```

The export logic uses [`codebase_rag/services/graph_service.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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

```bash
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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py) and updates the graph through [`graph_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py) | Central Typer definition and command registration |
| [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py) | Core async entry points: `main_single_query`, `main_async`, `main_optimize_async` |
| [`codebase_rag/graph_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_updater.py) | Repository-to-Memgraph synchronization |
| [`codebase_rag/services/graph_service.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/services/graph_service.py) | Memgraph client wrapper for `export`, `query`, optimization |
| [`codebase_rag/mcp/client.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py) | MCP client for daemon communication |
| [`codebase_rag/trace/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/trace/cli.py) | `trace` sub-CLI implementation |

## Summary

- **`start`** launches interactive sessions with optional graph sync (lines 408–576, [`cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/cli.py))
- **`daemon`** manages the Memgraph+Qdrant background stack (line 1004, [`cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/cli.py))
- **`trace`** records live execution via dedicated sub-CLI (line 1028, [`cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/cli.py); implementation in [`trace/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/trace/cli.py))
- **`query`** operates through `start`'s REPL, powered by `main_single_query`/`main_async` in [`main.py`](https://github.com/vitali87/code-graph-rag/blob/main/main.py)
- **`export`** dumps graphs to JSON using [`graph_service.py`](https://github.com/vitali87/code-graph-rag/blob/main/graph_service.py) (lines 894–926, [`cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/cli.py))
- **`optimize`** runs transformation passes with LLM orchestration (lines 834–892, [`cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/graph_updater.py) synchronization step and enters the REPL immediately. Your natural-language prompts route directly to `main_single_query` in [`main.py`](https://github.com/vitali87/code-graph-rag/blob/main/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.