# How to Configure code-graph-rag: Environment Variables, CLI Flags, and Code Examples

> Configure code-graph-rag easily using environment variables, CLI flags like --repo, or programmatic setup with CGRConfig for efficient graph building and RAG.

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

---

**Configure code-graph-rag by setting required environment variables like `OPENAI_API_KEY`, using CLI flags such as `--repo` and `--vector-store`, or instantiating the `CGRConfig` dataclass programmatically to control the graph-building and RAG pipeline.**

code-graph-rag is a Python framework that constructs a graph representation of any codebase and enables semantic search via Retrieval-Augmented Generation (RAG). According to the vitali87/code-graph-rag source code, the system aggregates settings through three primary mechanisms: environment variables, command-line interface (CLI) arguments, and configuration objects defined in [`codebase_rag/workspaces/models.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/models.py).

## Configuration Mechanisms

### Environment Variables

The framework reads critical secrets and endpoint URLs from the environment before invoking external APIs. In [`codebase_rag/workspaces/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/constants.py), the following variables are declared as required or optional defaults:

- `OPENAI_API_KEY` – Your OpenAI API token for generating embeddings and completions.
- `VECTOR_STORE_URL` – Endpoint URL for the vector store backend (e.g., Pinecone, Weaviate, or local Qdrant).
- `VECTOR_STORE_API_KEY` – Authentication token for the vector store provider, if applicable.

Set these in your shell or `.env` file before running the pipeline.

### CLI Flags

The `cgr` command-line interface, implemented in [`codebase_rag/workspaces/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/cli.py), exposes parameters that override environment defaults. Key flags include:

- `--repo` – URL or local path to the target Git repository.
- `--embedder` – Embedding provider selection (e.g., `openai`, `huggingface`).
- `--vector-store` – Backend for vector storage (e.g., `qdrant`, `pinecone`).
- `--output-dir` – Workspace directory for generated graphs and logs (default: `./cgr_workspace`).
- `--embedder-model` – Specific model name, such as `text-embedding-ada-002`.
- `--chunk-size` – Number of lines per code chunk to embed.
- `--prune-threshold` – Similarity threshold below which graph edges are removed to reduce noise.

### Programmatic Configuration

For custom applications, instantiate the `CGRConfig` dataclass directly and pass it to the `RAGEngine` class defined in [`codebase_rag/rag_engine.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/rag_engine.py). This approach bypasses CLI parsing and environment variable scanning, allowing dynamic configuration at runtime.

## Step-by-Step Setup Guide

Follow these steps to configure and run the pipeline:

1. **Install dependencies**  
   Run `pip install -r requirements.txt` to install the required packages listed in the repository root.

2. **Export environment variables**  
   ```bash
   export OPENAI_API_KEY="sk-..."
   export VECTOR_STORE_URL="http://localhost:6333"
   export VECTOR_STORE_API_KEY="optional-key"
   ```

3. **Create a workspace directory**  
   Choose a folder to hold the generated graph, embeddings, and logs:  
   ```bash
   mkdir -p ./cgr_workspace
   ```

4. **Execute the CLI**  
   ```bash
   cgr \
     --repo https://github.com/your/project.git \
     --embedder openai \
     --vector-store qdrant \
     --output-dir ./cgr_workspace \
     --chunk-size 200
   ```

   This command clones the repository, parses the AST into a Neo4j-compatible graph, generates embeddings, and stores vectors in the configured backend.

5. **Adjust advanced settings**  
   Modify `--embedder-model` to switch between OpenAI models, tune `--chunk-size` for optimal retrieval granularity, or set `--prune-threshold 0.05` to filter low-relevance graph edges.

6. **Query the resulting graph**  
   Use the REPL mode or import the engine directly:  
   ```bash
   python -m codebase_rag.main --query "How does the authentication flow work?"
   ```

## Key Configuration Files

Reference these source files when customizing behavior:

- [`codebase_rag/workspaces/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/constants.py) – Declares environment variable keys and default constant values.
- [`codebase_rag/workspaces/models.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/models.py) – Defines the `CGRConfig` Pydantic model that validates configuration schemas.
- [`codebase_rag/workspaces/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/cli.py) – Implements the `argparse` logic that maps CLI flags to the config model.
- [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py) – Entry point that loads the config, initializes the graph builder, embedder, and vector store, then executes the pipeline.
- [`codebase_rag/embedder.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/embedder.py) – Wrapper abstraction for embedding providers (OpenAI, HuggingFace).
- [`codebase_rag/vector_store.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/vector_store.py) – Interface for vector-store backends.

## Configuration Code Examples

### Programmatic Setup

```python
from codebase_rag.rag_engine import RAGEngine
from codebase_rag.workspaces.models import CGRConfig

cfg = CGRConfig(
    repo_url="https://github.com/your/project.git",
    embedder="openai",
    embedder_model="text-embedding-ada-002",
    vector_store="qdrant",
    output_dir="./cgr_workspace",
    chunk_size=200,
)

engine = RAGEngine(cfg)
answer = engine.query("Explain the caching strategy used in the project.")
print(answer)

```

### CLI Usage

```bash
cgr \
  --repo https://github.com/your/project.git \
  --embedder openai \
  --vector-store qdrant \
  --output-dir ./cgr_workspace \
  --chunk-size 300 \
  --prune-threshold 0.05

```

## Summary

- **Environment variables** in [`codebase_rag/workspaces/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/constants.py) handle secrets and endpoint URLs like `OPENAI_API_KEY` and `VECTOR_STORE_URL`.
- **CLI flags** parsed in [`codebase_rag/workspaces/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/cli.py) allow runtime overrides for repository sources, embedding models, and output directories.
- **The `CGRConfig` dataclass** in [`codebase_rag/workspaces/models.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/models.py) serves as the single source of truth, consumed by `RAGEngine` in [`codebase_rag/rag_engine.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/rag_engine.py).
- The entry point in [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py) orchestrates the pipeline: graph construction, embedding generation, and vector storage.

## Frequently Asked Questions

### What environment variables are required to run code-graph-rag?

You must set `OPENAI_API_KEY` for embedding generation and optional completions, plus `VECTOR_STORE_URL` to point to your vector database backend. If your vector store requires authentication, also set `VECTOR_STORE_API_KEY`. These names are defined in [`codebase_rag/workspaces/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/constants.py).

### Can I use code-graph-rag without the CLI?

Yes. Instantiate the `CGRConfig` dataclass programmatically with your desired parameters and pass it to the `RAGEngine` class imported from [`codebase_rag/rag_engine.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/rag_engine.py). This approach bypasses CLI argument parsing and is suitable for integrating the framework into larger Python applications.

### How do I change the embedding model?

Use the `--embedder-model` CLI flag (e.g., `--embedder-model text-embedding-ada-002`) or set the corresponding attribute on the `CGRConfig` object before initializing the engine. The embedder logic in [`codebase_rag/embedder.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/embedder.py) dispatches to the selected provider based on this value.

### Where is the configuration schema defined?

The configuration schema is defined by Pydantic models in [`codebase_rag/workspaces/models.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/models.py), primarily within the `CGRConfig` class. This model aggregates settings from environment variables and CLI flags, performing validation before the pipeline executes in [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py).