Command Line Interface Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Command Line Interface (CLI) for code-review-graph serves as the primary entry point for managing a local-first, token-efficient knowledge graph used for code reviews. It provides developers with tools for initial setup, graph construction, incremental updates, and integration with various AI coding platforms via the Model Context Protocol (MCP).
The CLI is designed to be user-friendly, offering colored terminal output, automated platform detection, and a suite of commands that handle the lifecycle of the code knowledge graph—from initial parsing to interactive visualization. Sources: code_review_graph/cli.py:34-122, CLAUDE.md:8-16
Core Commands and Usage
The CLI is structured into several functional categories including setup, graph management, visualization, and server operations.
Initialization and Setup
The install (aliased as init) command is the starting point for most users. It automatically detects installed AI coding tools (such as Claude Code, Cursor, Zed, or Windsurf) and configures the necessary MCP settings and skills. Sources: code_review_graph/cli.py:155-224, code_review_graph/skills.py:27-142
The installation flow automates the integration of the graph server into various development environments.
Graph Lifecycle Management
Commands like build and update manage the SQLite-backed graph store. While build performs a full re-parse of the codebase, update utilizes Git-based change detection to incrementally refresh only modified files, significantly reducing processing time to under 2 seconds for large projects. Sources: code_review_graph/cli.py:465-515, README.zh-CN.md:118-124
| Command | Purpose | Key Arguments |
|---|---|---|
build | Full graph construction | --skip-postprocess, --data-dir |
update | Incremental graph refresh | --base <ref>, --brief, --verify |
status | Display graph metrics | --repo |
postprocess | Manual trigger for flows/FTS | --no-flows, --no-communities |
Sources: code_review_graph/cli.py:465-602
MCP Server Operations
The serve command (aliased as mcp) starts a FastMCP server. This server exposes the graph's capabilities to AI agents through a standardized interface. Sources: code_review_graph/main.py:65-98
Server Modes
- Stdio Mode (Default): Communicates via standard input/output, ideal for local agent integration like Claude Code.
- HTTP Mode: Triggered with
--http, it starts a streamable HTTP server on localhost (default port 5555). - Auto-Watch: By using
--auto-watch, a background daemon thread is started to monitor filesystem changes and update the graph in real-time.
Sources: code_review_graph/cli.py:734-758, code_review_graph/main.py:1003-1025
Interaction between an AI Agent and the CRG CLI serving as an MCP host.
Visualization and Documentation
The CLI includes tools to transform raw graph data into human-readable formats and documentation.
Interactive Visualization
The visualize command generates a self-contained D3.js interactive HTML graph. It supports different rendering modes to handle varying codebase sizes. Sources: code_review_graph/visualization.py:343-388
- Full Mode: Renders every node (default for smaller graphs).
- Community Mode: Aggregates nodes by communities detected via the Leiden algorithm.
- File Mode: Aggregates nodes by their source files.
- Auto Mode: Automatically switches to community mode if the node count exceeds a threshold (typically 3000 nodes).
Sources: code_review_graph/visualization.py:27-32, code_review_graph/cli.py:613-640
Wiki Generation
The wiki command generates a Markdown-based wiki in the .code-review-graph/wiki/ directory. It uses the detected community structure to create overview pages for different modules of the codebase. Sources: code_review_graph/tools/docs.py:236-267, tests/test_wiki.py:126-135
Repository Registry
For multi-repo support, the CLI provides a registry management system. This allows the MCP server to search and analyze relationships across different projects. Sources: code_review_graph/cli.py:397-425
# Register a repository
code-review-graph register /path/to/project --alias my-project
# List all registered repositories
code-review-graph repos
# Remove a repository
code-review-graph unregister my-project
Sources: code_review_graph/cli.py:28-32, code_review_graph/cli.py:400-415
Advanced Configuration
Data Directory Management
Users can specify an external directory for the graph database using the --data-dir flag. This is particularly useful for storing graphs on network shares or specific volumes while keeping the repository clean. Sources: code_review_graph/cli.py:438-448
Embedding and Search
The embed command computes vector embeddings for nodes to enable semantic search capabilities. It supports multiple providers:
- Local: Uses
sentence-transformers(requirespip install code-review-graph[embeddings]). - Cloud: Supports OpenAI, Google Gemini, and MiniMax via environment variables.
Sources: code_review_graph/tools/docs.py:27-56, code_review_graph/cli.py:581-597
The CLI for code-review-graph provides a comprehensive suite of tools for both human developers and AI agents to navigate complex codebases with minimal token overhead. By bridging the gap between raw source code and structural knowledge, it enables faster and more accurate code reviews. Sources: CLAUDE.md:16-25, code_review_graph/cli.py:34-70