cli-reference.md

description	Complete CLI reference for Code-Graph-RAG commands and Makefile targets.

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 help
cgr help start
cgr help daemon logs

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 and importers, 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 context	Print a graph-ranked context slice for a symbol, location or task within a token budget: source, caller lines, callee signatures, types, tests, docs.
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.

cgr start --repo-path /path/to/repo [OPTIONS]

Option	Description
--repo-path	Path to repository (defaults to current directory)
--update-graph	Parse and ingest the repository into the knowledge graph, then exit without starting the assistant (cgr start already syncs before it starts). Cannot be combined with -a/--ask-agent, --no-sync or --projects.
--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 this repository's project graph to a JSON path: what the project owns, the relationships that start there and the nodes they reach. Requires --update-graph. cgr export writes the whole shared graph.

cgr export

Export the knowledge graph to JSON. Without options the file holds every project in the shared graph.

cgr export -o OUTPUT [OPTIONS]

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.

cgr optimize <language> --repo-path /path/to/repo [OPTIONS]

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.

cgr stats [OPTIONS]

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.

cgr dead-code [OPTIONS]

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.

cgr duplicates [OPTIONS]

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 mcp-server

cgr index

Index a repository to protobuf for offline use.

cgr index -o ./index-output --repo-path ./my-project

cgr doctor

Check that the services, credentials and tools a session needs are in place.

cgr doctor

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 list-languages --verbose
cgr language remove-language <language-name>
cgr language cleanup-orphaned-modules

list-languages prints one row per language across all three parsing tiers: its name, file extensions, tier (tree-sitter, ast-grep or document), level of support (full, in development, structural or headings) and whether this install can parse it. A language marked no needs its extra, which the command names below the table. A second table shows the optional semantic frontends (libclang, go/types, Roslyn, javac, Jedi): whether each toolchain is found, the setting that selects it, and whether indexing will use it. The language name and extensions are never truncated, including in piped output. --verbose adds the tree-sitter node types each language maps to functions, classes, modules and calls.

add-grammar, remove-language and cleanup-orphaned-modules are contributor tools: they edit the code-graph-rag source checkout the running cgr comes from, never the current directory. An installed cgr (PyPI, pipx, uv tool install) refuses them with a non-zero exit and changes nothing; clone the repository and run them there. See Adding Languages.

cgr graph

Deterministic graph queries, printed as JSON, with no LLM in the path.

cgr graph resolve helper
cgr graph callers myrepo__1a2b3c4d.pkg.util.helper --depth 2
cgr graph tests-reaching myrepo__1a2b3c4d.pkg.util.helper --project myrepo__1a2b3c4d

The project is --project, or else the one --repo-path (default .) was indexed as. The exit status tells an empty answer apart from a question the graph cannot answer, and a refusal prints nothing on stdout:

Status	Meaning
0	The JSON answer. [] means the name is in the graph and nothing matches it.
3	The project is not indexed, or, without --project, the directory was never indexed. The message on stderr names close matches.
4	callers, callees, implementors, overrides, importers or tests-reaching was given a qualified name the graph does not hold. The message names close matches, or points at cgr graph resolve.

resolve answers [] when no name matches, and definition answers {"found": false, ...} for a qualified name it does not find; neither exits with 4.

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)