# Configuration Options for code-graph-rag: Environment Variables, CLI Flags, and Dataclass Settings

> Explore code-graph-rag configuration options: use environment variables for secrets, CLI flags for runtime overrides, and the CGRConfig dataclass for programmatic control. Optimize your setup easily.

- 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 via environment variables for secrets, CLI flags for runtime overrides, and the `CGRConfig` dataclass for programmatic control.**

code-graph-rag is a Python-based framework that constructs a code graph from repositories and enables Retrieval-Augmented Generation (RAG) for querying source code. Understanding the available configuration options allows you to customize embedding providers, vector store backends, and graph construction parameters to match your specific infrastructure requirements.

## Configuration Mechanisms Overview

The framework implements a layered configuration strategy defined across three core files: [`codebase_rag/workspaces/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/constants.py) for environment defaults, [`codebase_rag/workspaces/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/cli.py) for argument parsing, and [`codebase_rag/workspaces/models.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/models.py) for schema validation. These layers cascade from system-level environment variables to explicit code-level settings.

### Environment Variables

Sensitive credentials and endpoint URLs are sourced from environment variables declared in [`codebase_rag/workspaces/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/constants.py). The system expects these variables to be set before initializing the pipeline:

- **OPENAI_API_KEY** – Authentication token for OpenAI API access
- **VECTOR_STORE_URL** – Endpoint URL for vector store providers (Pinecone, Weaviate, or local Qdrant)
- **VECTOR_STORE_API_KEY** – Optional authentication key depending on the provider

### Command-Line Interface Flags

The `cgr` entry point implemented in [`codebase_rag/workspaces/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/cli.py) exposes an `argparse`-based interface that maps arguments to the configuration model. Key flags include:

- **`--repo`** – Target repository URL or local path to analyze
- **`--embedder`** – Embedding provider selection (e.g., `openai`)
- **`--vector-store`** – Vector database backend (e.g., `qdrant`)
- **`--output-dir`** – Workspace directory for generated graphs and logs (default: `./cgr_workspace`)

### Programmatic Configuration

For embedded use within larger applications, instantiate the `CGRConfig` dataclass directly from [`codebase_rag/workspaces/models.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/models.py). The `RAGEngine` class in [`codebase_rag/rag_engine.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/rag_engine.py) accepts this configuration object to initialize the pipeline without invoking the CLI.

## CLI Flags and Options

The [`codebase_rag/workspaces/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/cli.py) module parses the following arguments that override default settings:

1. **`--repo`** – Specifies the target Git repository URL or local filesystem path
2. **`--embedder`** – Selects the embedding provider (options: `openai`, `huggingface`)
3. **`--vector-store`** – Configures the vector database backend
4. **`--output-dir`** – Defines the workspace directory for artifacts
5. **`--embedder-model`** – Specifies the model name (e.g., `text-embedding-ada-002`)
6. **`--chunk-size`** – Controls the number of lines per code chunk for embedding
7. **`--prune-threshold`** – Sets the minimum edge weight for graph pruning to maintain compactness

## Advanced Configuration Parameters

Beyond basic connectivity, fine-tune the graph construction and retrieval behavior through these settings defined in the `CGRConfig` schema:

- **Chunk Size** (`--chunk-size`) – Determines how source code is segmented before embedding. Smaller values increase granularity but require more storage.
- **Graph Pruning** (`--prune-threshold`) – Removes low-weight edges from the Neo4j-compatible graph to reduce noise, specified as a float between 0.0 and 1.0.
- **Embedding Model** (`--embedder-model`) – Overrides the default model selection for custom embedding providers configured in [`codebase_rag/embedder.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/embedder.py).

## Programmatic Configuration Example

Instantiate the configuration directly when integrating code-graph-rag as a library:

```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 Example

Execute the full pipeline via the command line with explicit overrides:

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

```

This command triggers the sequence defined in [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py): repository cloning, AST parsing, graph building, embedding generation, and vector store population.

## Summary

- **Environment variables** in [`constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/constants.py) handle secrets and endpoint configuration required for API access
- **CLI flags** in [`cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/cli.py) provide runtime overrides for repository selection, embedder choice, and output directories
- **`CGRConfig` dataclass** in [`models.py`](https://github.com/vitali87/code-graph-rag/blob/main/models.py) enables type-safe programmatic configuration when embedding the framework
- **Advanced parameters** like `--chunk-size` and `--prune-threshold` control the granularity and density of the generated code graph
- **`RAGEngine`** class serves as the primary entry point for executing queries against configured workspaces

## Frequently Asked Questions

### How do I switch from OpenAI to a local embedding provider?

Modify the `--embedder` flag to specify your local provider (e.g., `huggingface`) and update the `--embedder-model` path accordingly. Ensure the corresponding environment variables for your local service are set in [`codebase_rag/workspaces/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/constants.py) or passed directly to `CGRConfig` when using the programmatic interface.

### Where does code-graph-rag store the generated graph files?

The framework writes all artifacts to the directory specified by `--output-dir` (default: `./cgr_workspace`). This includes the Neo4j-compatible graph export, embedding caches, and processing logs as orchestrated by [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py).

### Can I configure the vector store connection without environment variables?

Yes. While [`constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/constants.py) defines environment variable names as defaults, you can bypass environment-based configuration by explicitly setting the `vector_store_url` and `vector_store_api_key` parameters when constructing a `CGRConfig` instance programmatically in [`codebase_rag/workspaces/models.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/models.py).

### What happens if I don't set the prune threshold?

If `--prune-threshold` is omitted, [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py) uses the default value defined in `CGRConfig`, typically retaining all graph edges. This results in a denser graph that may impact query performance but preserves complete relationship mappings from the AST analysis.