Skip to content

cli-reference.md

Latest commit

 

History

History
205 lines (160 loc) · 8.86 KB

cli-reference.md

File metadata and controls

205 lines (160 loc) · 8.86 KB
Raw
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 database 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.

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

cgr export -o my_graph.json

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 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 model credentials, judged by the same rule cgr start applies (a local Ollama model needs no key); 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)