CLI Reference¶
The cgr command is the main entry point for Code-Graph-RAG.
Built-in Help¶
List commands by workflow or show the detailed page for a command:
cgr COMMAND --help displays the same command-specific information.
Command Overview¶
Every top-level command, from the CLI's own help registry:
| Command | Description |
|---|---|
cgr start |
Open the code assistant for a repository or workspace |
cgr optimize |
Run a language-focused code optimisation session |
cgr mcp-server |
Serve cgr tools over stdio or HTTP |
cgr index |
Write an offline protobuf index for a repository |
cgr export |
Export the shared graph, or chosen projects, to JSON |
cgr graph-loader |
Summarise an exported graph JSON file |
cgr stats |
Show graph node and relationship counts |
cgr dead-code |
Report code that appears unreachable from known entry points |
cgr duplicates |
Report structurally duplicated functions and methods |
cgr delete-project |
Delete one project without changing other indexed projects |
cgr language |
Manage language grammars and parser metadata |
cgr daemon |
Manage the shared Memgraph and Qdrant stack |
cgr trace |
Ingest runtime call traces as dynamic CALLS edges |
cgr edits |
Show or undo recorded edit transactions (multi-file edits applied through cgr). |
cgr graph |
Deterministic graph queries (resolve, definition, callers, callees, implementors, overrides, importers, tests-reaching) as JSON, no LLM. |
cgr check |
Report the structural delta of the working tree against a git ref: dangling callers, arity findings, new duplicates, new import cycles, tests reaching the edited symbols. |
cgr rename |
Rename a definition everywhere the graph references it (definition, call and reference sites, imports, overrides, all); refuses on guessed sites. |
cgr workspace |
Manage named groups of repositories |
cgr stop |
Stop the shared stack (alias for cgr daemon down) |
cgr status |
Show stack state and the last sync time for each project |
cgr doctor |
Check dependencies, services, and configuration |
cgr help |
Show help for a command |
cgr verify-index |
Verify a protobuf index against its provenance manifest |
cgr diff-index |
Structural diff between two protobuf index snapshots |
Core Commands¶
cgr start¶
Parse a repository and/or start the interactive query CLI.
| Option | Description |
|---|---|
--repo-path |
Path to repository (defaults to current directory) |
--update-graph |
Parse and ingest the repository into the knowledge graph |
--clean |
Destructive. Delete every project from the shared graph and clear the selected repository's sync cache. With --update-graph, rebuild after deletion. Asks for confirmation when other projects would be destroyed. |
-y, --yes |
Answer yes to destructive confirmations, such as the one --clean asks. Required when --clean runs non-interactively and other projects would be destroyed, or when the existing projects cannot be listed. |
--batch-size |
Override Memgraph flush batch size |
--orchestrator |
Specify provider:model for main operations (e.g., anthropic:claude-sonnet-5, google:gemini-3.6-flash, ollama:qwen2.5-coder) |
--cypher |
Specify provider:model for graph queries (e.g., anthropic:claude-sonnet-5, google:gemini-3.5-flash-lite, ollama:qwen2.5-coder) |
-o, --output |
Write the updated graph to a JSON path. Requires --update-graph. |
cgr export¶
Export the knowledge graph to JSON. Without options the file holds every project in the shared graph.
| Option | Description |
|---|---|
-o, --output |
File to write. Checked before the graph is read: a directory, or a path that cannot be written, is a one-line error. |
--project-name, -n |
Export only this project: what it owns, the relationships that start there, and the nodes they reach. Repeatable. |
--workspace |
Export only the projects of workspace NAME. |
A name that is not indexed is an error that lists the projects that are. A
scoped file records its projects under metadata.projects. --batch-size and
--json are deprecated and ignored with a warning; --no-json is an error.
cgr optimize¶
AI-powered codebase optimisation.
| Option | Description |
|---|---|
--repo-path |
Path to repository |
--orchestrator |
Specify provider:model for operations |
--batch-size |
Override Memgraph flush batch size |
--reference-document |
Path to reference documentation for guided optimisation |
Supported languages: python, javascript, typescript, rust, go, java, scala, c, cpp
cgr stats¶
Count the nodes and relationships in the shared graph, by label and type. Without options the totals cover every indexed project, followed by one line per project when there is more than one.
| Option | Description |
|---|---|
--project-name, -n |
Count only this project: its containment tree, what it defines, and the relationships that start there. Repeatable. |
--workspace |
Count only the projects of workspace NAME. |
A name that is not indexed is an error that lists the projects that are.
cgr dead-code¶
Report functions and methods unreachable from any entry point (candidates for review, not a guaranteed delete list). See Dead Code Detection.
| Option | Description |
|---|---|
--project-name, -n |
Project to scan. Defaults to the sole indexed project. |
--entry-point, -e |
Treat symbols whose qualified name ends with this value as reachable roots. Repeatable. |
--decorator-root |
Treat symbols carrying this decorator as roots. Repeatable. |
--exclude |
Glob matched against a symbol's whole repo-relative file path to exclude it; quote it. Repeatable. |
--include-tests / --no-include-tests |
Treat test code as reachable roots. On by default. |
--classes / --no-classes |
Also report unreachable classes. Off by default. |
--format |
Output format: table (default) or json. |
--output, -o |
Write the report to a file instead of stdout. |
--fail-on-found |
Exit with code 1 when any candidate is found (useful in CI). |
cgr duplicates¶
Report groups of structurally duplicated functions and methods (copy-pastes, including renamed and lightly edited copies). See Duplicate Code Detection.
| Option | Description |
|---|---|
--project-name, -n |
Project to scan. Defaults to the sole indexed project. |
--threshold |
Minimum similarity for a near-duplicate pair, 0-1. Default 0.8. |
--min-size |
Minimum skeleton size (tree nodes) for a function to be considered. Default 15. |
--exact-only |
Report only identical-fingerprint clone groups; skip similarity scoring. |
--exclude |
Glob matched against a symbol's whole repo-relative file path to exclude it; quote it. Repeatable. |
--format |
Output format: table (default) or json. |
--output, -o |
Write the report to a file instead of stdout. |
--fail-on-found |
Exit with code 1 when any duplicate is found (useful in CI). |
cgr mcp-server¶
Serve cgr tools to MCP clients over stdio or HTTP.
cgr index¶
Index a repository to protobuf for offline use.
cgr doctor¶
Check that the services, credentials and tools a session needs are in place.
It reports, one line per check: the Docker daemon; a connection to the configured graph engine (and, when reachable, the graph's structural integrity); the orchestrator and Cypher models: for a key-based provider, whether its credentials pass the rule cgr start applies (reported as "credentials present", with no network call); for a local Ollama model, whether Ollama answers at OLLAMA_BASE_URL and has the model pulled (reported as "ready", "not reachable" or "not pulled", with the ollama pull command to run); and ripgrep. The exit status is 1 when any check fails. On a terminal that cannot display ✓/✗ the marks are printed as PASS/FAIL.
cgr language¶
Manage language support.
cgr language add-grammar <language-name>
cgr language add-grammar --grammar-url <url>
cgr language list-languages
cgr language remove-language <language-name>
Makefile Commands¶
| Command | Description |
|---|---|
make help |
Show this help message |
make all |
Install everything for full development environment (deps, grammars, hooks, tests) |
make install |
Install project dependencies with full language support |
make python |
Install project dependencies for Python only |
make dev |
Setup development environment (install deps + pre-commit hooks) |
make test |
Run unit tests only (fast, no Docker) |
make test-parallel |
Run unit tests in parallel (fast, no Docker) |
make test-integration |
Run integration tests (requires Docker) |
make test-all |
Run all tests including integration and e2e (requires Docker) |
make test-parallel-all |
Run all tests in parallel including integration and e2e (requires Docker) |
make clean |
Clean up build artifacts and cache |
make build-grammars |
Build grammar submodules |
make watch |
Watch repository for changes and update graph in real-time |
make readme |
Regenerate README.md from codebase |
make lint |
Run ruff check |
make format |
Run ruff format |
make typecheck |
Run type checking with ty |
make check |
Run all checks: lint, typecheck, test |
make release |
Build, verify, and publish the current pyproject version to PyPI, then tag and create a GitHub Release |
make jvm-agent |
Build the JVM runtime tracing agent (requires JDK 24+) |
make pre-commit |
Run all pre-commit checks locally (comprehensive test before commit) |