CLI Guide

CLI Guide

Complete command-line interface documentation for CodeGraph.

Table of Contents

Quick Reference

Tool Purpose Typical Usage
python -m src.api.cli run Start REST API server Production/development server
codegraph import Import project to CPG Clone repo + create CPG
codegraph projects Manage imported projects List, activate, delete projects
security-audit full Security audit Scan project for vulnerabilities
patch-review analyze Code review Analyze codebase for issues
patch-review github PR review Review GitHub pull requests
generate-docs full Documentation generation Generate full project docs + ChromaDB index
codegraph gocpg GoCPG operations CPG stats, queries, branches, hooks, watch
codegraph patterns Structural pattern analysis Scan rules, search patterns, apply fixes

codegraph CLI

Main CLI for importing projects and managing the CodeGraph system.

Installation

# From the codegraph directory
pip install -e .

# Or run directly
python -m src.cli.import_commands [command] [options]

Import Command

Import a project from Git repository or local path.

codegraph import [options]

Options:

Option Description Default
--repo Git repository URL -
--path Local path to source code -
--language Programming language (auto-detect if not specified) auto
--branch Git branch to clone main
--shallow Use shallow clone true
--include Paths to include (multiple) all
--exclude Paths to exclude (multiple) none
--mode Import mode: full, selective, incremental full
--workspace CPG workspace path auto
--domain-name Custom domain name auto
--group Project group name default
--memory GoCPG memory in GB 16
--batch-size DuckDB batch size 10000
--docker Use Docker for GoCPG false
--no-docs Skip documentation import false
--no-plugin Skip domain plugin creation false

Examples:

# Import from GitHub
codegraph import --repo https://github.com/postgres/postgres --branch REL_17_STABLE

# Import local code with Docker
codegraph import --path ./myproject --docker

# Import with specific language
codegraph import --repo https://github.com/org/repo --language python

# Selective import (specific paths only)
codegraph import --path ./code --mode selective --include src/core src/api

# Import to specific group
codegraph import --repo https://github.com/org/repo --group security-team

Projects Management

Manage imported projects.

codegraph projects [subcommand] [options]

List Projects

codegraph projects list [options]
Option Description
--group Filter by group name
--language Filter by language
--active Show only active project

Examples:

# List all projects
codegraph projects list

# List projects in a group
codegraph projects list --group security-team

# Show active project only
codegraph projects list --active

Activate Project

codegraph projects activate <name> [--group <group>]

Delete Project

codegraph projects delete <name> [options]
Option Description
--group Project group name
--delete-files Also delete CPG and DuckDB files

Project Info

codegraph projects info <name> [--group <group>]

Single Step Commands

Execute individual pipeline steps.

# Clone repository
codegraph clone --repo <url> [--branch main] [--shallow] [--depth 1] [--output dir]

# Detect programming language
codegraph detect --path <source_path>

# Create CPG (outputs DuckDB directly via GoCPG)
codegraph cpg --path <source_path> [--language c] [--output db.duckdb]

# Validate CPG database
codegraph validate --db <duckdb_path>

# List supported languages
codegraph languages

Supported Languages:

Language Extensions
c .c, .h
cpp .cpp, .hpp, .cc, .cxx
python .py
java .java
go .go
javascript .js, .jsx
typescript .ts, .tsx
kotlin .kt, .kts
csharp .cs
php .php
1c .bsl, .os

GoCPG CLI

Direct access to GoCPG operations via the unified Python wrapper.

codegraph gocpg <subcommand> [options]

gocpg stats — CPG Statistics

codegraph gocpg stats [--db PATH]
Option Default Description
--db from config DuckDB file path

Displays total nodes, edges, methods, calls, files, type declarations, and database size.

gocpg query — Execute SQL Query

codegraph gocpg query "SQL" [--db PATH]
Option Default Description
sql (required) SQL query string
--db from config DuckDB file path

Example:

codegraph gocpg query "SELECT COUNT(*) FROM nodes_method"
codegraph gocpg query "SELECT full_name FROM nodes_method LIMIT 10" --db data/projects/postgres.duckdb

gocpg frontends — List Language Frontends

codegraph gocpg frontends

Lists all available language frontends with their supported file extensions and availability status.

gocpg metrics — Validate Metrics

codegraph gocpg metrics [--input PATH] [--verbose]
Option Default Description
--input, -i . Source file or directory
--verbose, -v false Show per-file details

gocpg branches — Branch Management

codegraph gocpg branches list [--db PATH]
codegraph gocpg branches switch NAME [--db PATH]
codegraph gocpg branches prune [--input PATH] [--db PATH]
Subcommand Description
list List tracked branches with commit SHA, file/node counts, and active status
switch NAME Switch the active CPG branch
prune Remove stale branches no longer present in the git repository
Option Default Description
--db from config DuckDB file path
--input, -i . Git repository path (for prune)

gocpg hooks — Git Hook Management

codegraph gocpg hooks install [--repo PATH] [--db PATH] [--hooks TYPES] [--lang LANG]
codegraph gocpg hooks uninstall [--repo PATH]
codegraph gocpg hooks status [--repo PATH]
Subcommand Description
install Install git hooks for automatic CPG updates on commit
uninstall Remove installed git hooks
status Show current hook installation status
Option Default Description
--repo . Repository path
--db from config DuckDB file path
--hooks all Comma-separated hook types
--lang auto-detect Language frontend

gocpg watch — File Watcher

codegraph gocpg watch --input PATH [--output PATH] [--lang LANG] [--debounce MS] [--webhook URL]
Option Default Description
--input, -i (required) Directory to watch
--output, -o from config DuckDB file path
--lang, -l auto-detect Language frontend
--debounce 500 Debounce interval in milliseconds
--webhook none Webhook URL for change notifications

Starts a background process that monitors file changes and incrementally updates the CPG. Press Ctrl+C to stop.

gocpg index — Create/Recreate Indexes

codegraph gocpg index [--db PATH]
Option Default Description
--db from config DuckDB file path

Creates or recreates DuckDB indexes for optimized query performance.

gocpg submodules — Submodule Management

codegraph gocpg submodules list [--db PATH]
codegraph gocpg submodules prune [--input PATH] [--db PATH]
Subcommand Description
list List tracked submodules with commit SHA and initialization status
prune Remove stale submodules no longer present in the repository
Option Default Description
--db from config DuckDB file path
--input, -i . Git repository path (for prune)

Patterns CLI

Structural pattern search, scanning, and rewriting via YAML rules and ad-hoc patterns.

codegraph patterns <subcommand> [options]

patterns scan — Run YAML Rules Against CPG

codegraph patterns scan [options]
Option Default Description
--db from config DuckDB file path
--rules from config Rule directory paths (multiple)
--rule all Run only a specific rule ID
--severity all Minimum severity: error, warning, info, hint
--incremental false Enable incremental evaluation
--format text Output format: json, sarif, text
--output stdout Write output to file

Examples:

# Scan with all rules
codegraph patterns scan

# Scan specific database with severity filter
codegraph patterns scan --db data/projects/postgres.duckdb --severity warning

# Scan with specific rule, output SARIF
codegraph patterns scan --rule no-unchecked-malloc --format sarif --output findings.sarif

# Incremental scan (only changed files)
codegraph patterns scan --incremental

codegraph patterns search "<pattern>" --lang LANG [options]
Option Default Description
pattern (required) Structural pattern string (e.g. "malloc($SIZE)")
--lang (required) Source language (c, go, python, javascript, etc.)
--db from config DuckDB file path
--max-results 100 Maximum results to return

Examples:

# Search for unchecked malloc calls in C
codegraph patterns search "malloc($SIZE)" --lang c

# Search for SQL string concatenation in Python
codegraph patterns search "\"SELECT \" + $VAR" --lang python --max-results 50

patterns fix — Apply Fixes from YAML Rule Templates

codegraph patterns fix [options]
Option Default Description
--db from config DuckDB file path
--rules from config Rule directory paths (multiple)
--rule all Run only a specific rule ID
--dry-run false Preview fixes without applying

Examples:

# Preview all fixes (dry run)
codegraph patterns fix --dry-run

# Apply fixes for a specific rule
codegraph patterns fix --rule use-safe-string-concat

# Apply fixes from custom rules directory
codegraph patterns fix --rules ./my-rules --dry-run

patterns list — List Loaded Rules

codegraph patterns list [--db PATH]

Lists all pattern rules loaded into the CPG database with their ID, severity, category, language, and whether they have a fix template.

patterns stats — Show Pattern Statistics

codegraph patterns stats [--db PATH]

Displays aggregated pattern matching statistics: total findings, breakdown by severity, category, and rule.

patterns generate — LLM-Generate YAML Rule

codegraph patterns generate "<description>" --lang LANG [--output FILE]
Option Default Description
description (required) Natural language rule description
--lang (required) Target language
--output stdout Write YAML to file

Examples:

# Generate a rule from description
codegraph patterns generate "find unchecked malloc calls" --lang c

# Generate and save to file
codegraph patterns generate "detect SQL injection via string concatenation" --lang python --output sql_injection.yaml

API Server CLI

Module: src.api.cli

python -m src.api.cli <command> [options]

run - Start API Server

python -m src.api.cli run [options]
Option Default Description
--host 0.0.0.0 Host address to bind to
--port 8000 Port number to listen on
--workers 1 Number of uvicorn worker processes
--reload false Enable auto-reload for development
--log-level info Logging level (debug, info, warning, error)

Examples:

# Start server with defaults
python -m src.api.cli run

# Development mode with auto-reload
python -m src.api.cli run --reload --log-level debug

# Production with multiple workers
python -m src.api.cli run --host 0.0.0.0 --port 8000 --workers 4

init-db - Initialize Database

python -m src.api.cli init-db

migrate - Run Migrations

python -m src.api.cli migrate [--revision REVISION]

create-admin - Create Admin User

python -m src.api.cli create-admin --username USERNAME --password PASSWORD [--email EMAIL]

security-audit CLI

Security scanning CLI for Python/Django projects.

Module: src.cli.security_audit

python -m src.cli.security_audit <command> [options]

Full Audit

Run comprehensive security audit with multiple output formats.

security-audit full --path <project_path> [options]
Option Short Description Default
--path -p Path to project to audit required
--output -o Output directory for reports ./security_reports
--format -f Output format(s): json, markdown, sarif, all json markdown sarif
--exclude-dirs Additional directories to exclude none
--no-cpg Skip CPG-based analysis (faster) false
--verbose -v Verbose output false

Examples:

# Full audit with all formats
security-audit full --path ./myproject

# JSON output only
security-audit full --path ./myproject --format json

# Exclude directories
security-audit full --path ./myproject --exclude-dirs vendor third_party

# Quick file-based scan only (no CPG)
security-audit full --path ./myproject --no-cpg

Output:

The audit generates reports in the specified directory: - security_audit_YYYYMMDD_HHMMSS.json - security_audit_YYYYMMDD_HHMMSS.md - security_audit_YYYYMMDD_HHMMSS.sarif

Quick Scan

Fast file-based security scan without full CPG analysis.

security-audit quick --path <project_path> [--output <file>]

Settings Scan

Scan Django settings file for security issues.

security-audit settings --path <settings_path>

Checks performed: - DEBUG = True in production - Weak SECRET_KEY - ALLOWED_HOSTS configuration - CSRF_COOKIE_SECURE - SESSION_COOKIE_SECURE - SECURE_SSL_REDIRECT - Hardcoded database credentials

Secrets Scan

Scan for hardcoded secrets and credentials.

security-audit secrets --path <project_path>

Detects: - API keys (AWS, GCP, Azure, GitHub, etc.) - Private keys (RSA, SSH) - Database connection strings - JWT secrets - OAuth tokens - Generic passwords in code

Vulnerability Severities

Severity Icon Description
Critical [X] Immediate action required
High [!] Address before deployment
Medium [~] Should be fixed
Low [o] Minor issues
Info [i] Informational

Excluded Directories (Default)

The scanner automatically excludes: - __pycache__, .git - .venv, venv, env - node_modules - .tox, .pytest_cache, .mypy_cache - migrations - static, media - dist, build

patch-review CLI

Automated code review using Code Property Graph analysis.

Module: src.patch_review.cli

python -m src.patch_review.cli [command] [options]

Analyze Command

Run security and dead code analysis on the entire codebase.

patch-review analyze [options]
Option Short Description Default
--type -t Analysis type: security, dead-code, all all
--severity -s Minimum severity: critical, high, medium, low, all all
--patterns -p Comma-separated pattern IDs to check all patterns
--limit -l Max findings per pattern 50

Examples:

# Full analysis (security + dead code)
patch-review analyze --db data/projects/postgres.duckdb

# Security only, critical severity
patch-review analyze --type security --severity critical

# Specific patterns
patch-review analyze --patterns SQL_INJECTION,BUFFER_OVERFLOW,DEAD_CODE

Diff Review

Review changes from a unified diff file.

patch-review diff [file] [options]
Option Description
file Path to diff file (or - for stdin)
--dead-code Include dead code analysis in review
--security-only Only run security analysis

Examples:

# Review a diff file
patch-review diff changes.diff

# Read from stdin
git diff | patch-review diff -

# With dead code analysis
patch-review diff changes.diff --dead-code

GitHub PR Review

Fetch and review a GitHub Pull Request.

patch-review github <pr_number> [options]
Option Description
--owner Repository owner (or GITHUB_OWNER env)
--repo Repository name (or GITHUB_REPO env)
--token GitHub token (or GITHUB_TOKEN env)
--post-review Post review comments to PR
--dead-code Include dead code analysis

Example:

patch-review github 123 --owner myorg --repo myrepo --token $GITHUB_TOKEN --post-review

GitLab MR Review

Fetch and review a GitLab Merge Request.

patch-review gitlab <mr_iid> [options]
Option Description
--project Project ID or path (or GITLAB_PROJECT_ID env)
--token GitLab token (or GITLAB_TOKEN env)
--post-review Post review comments to MR

Global Options

Option Short Description Default
--db -d Path to DuckDB CPG database data/projects/postgres.duckdb
--output -o Output format: json, markdown, summary, score markdown
--output-file -f Write output to file stdout
--verbose -v Enable verbose logging false
--quiet -q Only output result, no status messages false
--security-threshold Minimum security score to pass 60.0
--block-on-critical Block if any critical findings true

Benchmark & Analysis Tools

demo_benchmark.py

Demonstrates the benchmark framework with synthetic retrieval results.

python examples/demo_benchmark.py

Features: - Simulates vector, graph, and hybrid retrieval - Demonstrates P@K, R@K, F1@K, MRR, NDCG metrics - Reproducible results with random seed

demo_patch_review.py

Demonstrates the automated patch review pipeline.

python examples/demo_patch_review.py [--db data/projects/postgres.duckdb]

Output Files: - demo_review_output.json - Structured analysis results - demo_review_output.md - Markdown review report

tests/benchmark/run_benchmark.py

Full multi-scenario benchmark runner.

python tests/benchmark/run_benchmark.py [OPTIONS]
Argument Description
--quick Run quick benchmark (subset of queries)
--scenario N Run specific scenario (1-21)
--all-scenarios Run all 21 scenarios
--output DIR Output directory for results

Environment Variables

Variable Description Used By
DATABASE_URL PostgreSQL connection URL API server
GIGACHAT_CREDENTIALS GigaChat API credentials LLM provider
OPENAI_API_KEY OpenAI API key LLM provider
GOCPG_PATH GoCPG binary path Import tools
DUCKDB_PATH Path to DuckDB database All tools
LOG_LEVEL Default logging level All tools
GITHUB_TOKEN GitHub API token patch-review
GITHUB_OWNER Default repository owner patch-review
GITHUB_REPO Default repository name patch-review
GITLAB_TOKEN GitLab API token patch-review
GITLAB_PROJECT_ID Default GitLab project patch-review

Exit Codes

codegraph

Code Meaning
0 Command completed successfully
1 Error occurred
2 Invalid arguments

security-audit

Code Meaning
0 Audit completed successfully
1 Error or critical findings

patch-review

Code Meaning
0 Review approved / No critical findings
1 Review requests changes / High severity findings
2 Review blocks merge / Critical findings

CI/CD Integration

GitHub Actions

name: Security Analysis
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install -e .

      - name: Security Audit
        run: |
          security-audit full --path . --format sarif --output ./reports

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: reports/security_audit_*.sarif

      - name: Patch Review
        if: github.event_name == 'pull_request'
        run: |
          patch-review analyze --type security --severity high --output json > analysis.json
          exit_code=$?
          if [ $exit_code -eq 2 ]; then
            echo "Critical vulnerabilities found!"
            exit 1
          fi

GitLab CI

stages:
  - security

security_scan:
  stage: security
  script:
    - pip install -e .
    - security-audit full --path . --format json --output ./reports
    - patch-review analyze --type security --severity critical
  artifacts:
    reports:
      sast: reports/security_audit_*.json
  allow_failure: false

Troubleshooting

Database Connection Error

# Verify database exists and is readable
ls -la data/projects/postgres.duckdb

# Try with explicit path
patch-review analyze --db /full/path/to/data/projects/postgres.duckdb

No Findings

# Check with verbose logging
patch-review analyze --verbose

# Lower severity threshold
patch-review analyze --severity all

GoCPG Issues

# Check GoCPG stats
codegraph gocpg stats

# Verify GoCPG binary is accessible
codegraph gocpg frontends

Import Failures

# Check supported languages
codegraph languages

# Try with Docker
codegraph import --path ./code --docker

# Check import job status
codegraph jobs --status failed

File Editing CLI (S17)

Programmatic code editing with precise targeting and undo support.

Module: src.cli.edit_commands

codegraph edit <subcommand> [options]

Find Target

Locate a function, class, or method for editing.

codegraph edit find --target <name> [options]
Option Description
--target Name of function/class/method to find
--file Limit search to specific file
--type Entity type: function, class, method

Examples:

# Find a function
codegraph edit find --target heap_insert

# Find in specific file
codegraph edit find --target process_query --file src/executor/executor.c

# Find a class
codegraph edit find --target UserService --type class

Apply Edit

Apply code changes to a target.

codegraph edit apply --file <file> --target <target> --new-code <code> [options]
Option Description
--file File containing the target
--target Name of function/class/method
--new-code New code to insert (or path to file with @)
--preview Show diff without applying

Examples:

# Apply inline code
codegraph edit apply --file src/utils.py --target validate_input --new-code "def validate_input(data): return data.strip()"

# Apply from file
codegraph edit apply --file src/utils.py --target validate_input --new-code @new_function.py

# Preview changes
codegraph edit apply --file src/utils.py --target validate_input --new-code @fix.py --preview

Rename

Rename a symbol across the codebase.

codegraph edit rename --old <name> --new <name> [options]
Option Description
--old Current symbol name
--new New symbol name
--scope Limit to specific path

Examples:

# Rename function
codegraph edit rename --old processData --new process_data

# Rename within scope
codegraph edit rename --old handler --new request_handler --scope src/api/

Undo & History

# Undo last edit
codegraph edit undo

# Undo specific edit
codegraph edit undo --id <edit_id>

# Show edit history
codegraph edit history

Code Optimization CLI (S18)

AI-powered code optimization with approval workflow.

Module: src.cli.optimize_commands

codegraph optimize <subcommand> [options]

Analyze

Analyze code for optimization opportunities.

codegraph optimize analyze <path> [options]
Option Description
--performance Focus on performance optimizations
--security Focus on security improvements
--readability Focus on readability improvements
--all Analyze all categories (default)

Examples:

# Analyze directory
codegraph optimize analyze src/

# Performance-focused analysis
codegraph optimize analyze src/core/ --performance

# Security + readability
codegraph optimize analyze src/api/ --security --readability

View Suggestions

# List all suggestions
codegraph optimize list

# Show specific suggestion details
codegraph optimize show --id <suggestion_id>

Approve/Reject

# Approve a suggestion
codegraph optimize approve --id <suggestion_id>

# Reject with reason
codegraph optimize reject --id <suggestion_id> --reason "Not applicable to our use case"

Apply & Undo

# Apply all approved suggestions
codegraph optimize apply

# Undo last applied optimization
codegraph optimize undo

Standards Check CLI (S19)

Reference-guided standards enforcement using YAML documents.

Module: src.cli.standards_commands

codegraph standards <subcommand> [options]

Import & Validate

# Import standards document
codegraph standards import <document.yaml>

# Validate document syntax
codegraph standards validate <document.yaml>

Examples:

# Import company standards
codegraph standards import company_standards.yaml

# Validate before import
codegraph standards validate company_standards.yaml

List Rules

# List all imported rules
codegraph standards list

# List by category
codegraph standards list --category security

Check Code

codegraph standards check <path> [options]
Option Description
--severity Filter: error, warning, info
--category Filter by category (security, naming, etc.)

Examples:

# Check directory
codegraph standards check src/

# Check errors only
codegraph standards check src/ --severity error

# Check security rules only
codegraph standards check src/ --category security

Report & Clear

# Generate violation report
codegraph standards report src/ --output violations.json

# Clear all imported rules
codegraph standards clear

Dependencies CLI (S20)

Dependency analysis for vulnerabilities, updates, and compliance.

Module: src.cli.deps_commands

codegraph deps <subcommand> [options]

Scan Dependencies

codegraph deps scan [options]
Option Description
--project Path to project (default: current directory)
--include-dev Include dev dependencies
--output Output file for JSON results

Examples:

# Scan current project
codegraph deps scan

# Scan specific path with dev deps
codegraph deps scan --project ./myapp --include-dev

# Output to file
codegraph deps scan --output deps.json

Vulnerability Audit

codegraph deps audit [options]
Option Description
--severity Filter: critical, high, medium, low
--fail-on Exit with error on severity level
--report Output detailed report file

Examples:

# Full audit
codegraph deps audit

# Critical and high only
codegraph deps audit --severity critical,high

# CI/CD mode (fail on high)
codegraph deps audit --fail-on high

Outdated Packages

codegraph deps outdated [options]
Option Description
--direct-only Show only direct dependencies
--show-updates Show available update versions

License Compliance

codegraph deps licenses [options]
Option Description
--allowed Comma-separated allowed licenses
--fail-on Fail on specific license

Examples:

# Check all licenses
codegraph deps licenses

# Check against allowed list
codegraph deps licenses --allowed MIT,Apache-2.0,BSD-3-Clause

# Fail on GPL
codegraph deps licenses --fail-on GPL-3.0

SBOM Generation

codegraph deps sbom [options]
Option Description
--format Format: cyclonedx, spdx
--output Output file path
--include-vulnerabilities Include vulnerability data

Examples:

# Generate CycloneDX SBOM
codegraph deps sbom --format cyclonedx --output sbom.json

# Generate SPDX with vulnerabilities
codegraph deps sbom --format spdx --output sbom.spdx --include-vulnerabilities

Dependency Graph

# Show dependency tree
codegraph deps tree

# Show why a package is installed
codegraph deps why <package>

# Export graph
codegraph deps graph --format dot --output deps.dot

Composition CLI

Orchestrate multiple scenarios for complex analysis workflows.

Module: src.cli.composition_commands

codegraph composition <subcommand> [options]

Run Composite Query

codegraph composition run "<query>" [options]
Option Description
-o, --orchestrator Orchestrator scenario: s18, s19
-s, --scenarios Additional scenarios to include

Examples:

# Run with S18 orchestrator
codegraph composition run "Optimize the authentication module" -o s18

# Run with S19 orchestrator and extra scenarios
codegraph composition run "Check against company_standards.yaml" -o s19 -s s08

# Multi-scenario composition
codegraph composition run "Full security audit" -o s18 -s s02 -s s08

Apply Findings

codegraph composition apply <finding_id> -s <session_id> [options]
Option Description
-s, --session Session ID from composition run
--preview Preview changes without applying

Conflict Management

# Check for conflicts between findings
codegraph composition conflicts -s <session_id>

Configuration

# Show composition configuration
codegraph composition config

# List available orchestrator scenarios
codegraph composition scenarios

Documentation Generation CLI

Batch documentation generation from CPG data with ChromaDB indexing for semantic search.

Module: src.cli.generate_docs

python -m src.cli.generate_docs <command> [options]

Full Generation

Generate all 8 documentation sections, save to disk, and index in ChromaDB.

python -m src.cli.generate_docs full [options]
Option Short Description Default
--output -o Output directory for generated docs ./docs/generated
--language -l Language: en, ru en
--no-chromadb Skip ChromaDB indexing false
--verbose -v Verbose output false
--sections Specific sections to generate all

Examples:

# Generate full documentation in English
python -m src.cli.generate_docs full --output ./docs/generated

# Generate in Russian, skip ChromaDB
python -m src.cli.generate_docs full --language ru --no-chromadb

# Generate only specific sections
python -m src.cli.generate_docs full --sections mvd_doc coverage_doc diagram_doc

Generated Sections (in order):

Section Description
mvd_doc Project overview (Minimum Viable Documentation)
module_overview Module-level documentation
function_doc Function-level documentation
pipeline_doc Data flow / pipeline documentation
business_logic_doc Business rules (uses LLM)
type_doc Type statistics and conversions
coverage_doc Documentation coverage metrics
diagram_doc Call graph diagrams (Mermaid)

Output:

  • docs/generated/documentation_en_YYYYMMDD_HHMMSS.md - Combined document
  • docs/generated/sections/mvd_doc_en.md - Individual section files
  • ChromaDB generated_documentation collection - Indexed chunks for semantic search

Single Section

Generate a single documentation section.

python -m src.cli.generate_docs section <name> [--language en|ru]

Examples:

# Generate MVD overview
python -m src.cli.generate_docs section mvd_doc

# Generate coverage report in Russian
python -m src.cli.generate_docs section coverage_doc --language ru

Re-index Existing Files

Re-index previously generated documentation files into ChromaDB.

python -m src.cli.generate_docs index --path <docs_directory> [--language en|ru]

Statistics

Show ChromaDB collection statistics for generated documentation.

python -m src.cli.generate_docs stats

Exec Command (CI/CD)

The exec command provides non-interactive execution for CI/CD pipelines. Combined with --base-ref, it runs a PR security review that analyzes changed methods between a base Git ref and HEAD.

Basic Usage

# Run security review against last 5 commits
python -m src.cli exec --prompt "Review security" --base-ref HEAD~5

# Use specific database
python -m src.cli exec --prompt "Review security" --db data/projects/postgres.duckdb --base-ref origin/main

# Generate all output files
python -m src.cli exec --prompt "Review security" \
    --base-ref HEAD~5 \
    --output-file results.json \
    --sarif-file security.sarif \
    --comment-file pr_comment.md

Arguments

Argument Required Description
--prompt Yes Analysis prompt (e.g. “Review security”)
--db No Path to DuckDB CPG database (auto-resolves from active project)
--base-ref No Git ref for PR review (e.g. HEAD~5, origin/main)
--output-file No Path to write JSON results
--sarif-file No Path to write SARIF 2.1.0 output
--comment-file No Path to write PR comment markdown
--sandbox No Sandbox mode: read-only (default) or workspace-write
--output-schema No Path to JSON Schema file to validate output against

Exit Codes

Code Meaning
0 No security findings (clean)
1 Security findings detected or error

Output Files

JSON results (--output-file) follow the schema at .codegraph/security-review-schema.json:

{
  "findings": [
    {
      "finding_id": "f1",
      "pattern_id": "sql_injection",
      "severity": "critical",
      "method_name": "exec_query",
      "filename": "db.c",
      "line_number": 42,
      "description": "Potential SQL injection via unvalidated input"
    }
  ],
  "critical_count": 1,
  "high_count": 0,
  "medium_count": 0,
  "low_count": 0,
  "changed_methods": ["exec_query", "parse_input"],
  "total_findings": 1,
  "new_findings": 1,
  "fixed_findings": 0,
  "existing_findings": 0
}

The new_findings, fixed_findings, and existing_findings counts represent the delta between the base ref and HEAD, computed via fingerprinting (pattern_id:method_name:filename).

SARIF output (--sarif-file) produces SARIF 2.1.0 format via the standalone SARIFExporter (src/security/sarif_exporter.py), compatible with GitHub Security Alerts and other SARIF consumers. Each result includes a fingerprints.codegraph/v1 field for delta tracking.

PR comment (--comment-file) generates markdown with a severity summary table, per-finding details, and a Delta (New vs Fixed) section showing newly introduced and resolved findings.

Schema validation (--output-schema) validates the output JSON against a provided JSON Schema file after execution. Returns exit code 1 if validation fails. Requires the jsonschema Python package.

CI/CD Integration

GitHub Actions

security-review:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - name: Run security review
      run: |
        python -m src.cli exec --prompt "Review security" \
          --base-ref origin/main \
          --sarif-file security.sarif \
          --comment-file pr_comment.md
    - name: Upload SARIF
      uses: github/codeql-action/upload-sarif@v3
      with:
        sarif_file: security.sarif
    - name: Post PR comment
      if: github.event_name == 'pull_request'
      run: gh pr comment ${{ github.event.number }} --body-file pr_comment.md

GitLab CI

security-review:
  stage: test
  script:
    - python -m src.cli exec --prompt "Review security"
        --base-ref origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
        --sarif-file security.sarif
        --comment-file pr_comment.md
        --output-file results.json
    - |
      CRITICAL=$(python -c "import json; print(json.load(open('results.json'))['critical_count'])")
      if [ "$CRITICAL" -gt 0 ]; then
        echo "Critical security findings detected!"
        exit 1
      fi
  artifacts:
    paths:
      - security.sarif
      - pr_comment.md
    reports:
      sast: security.sarif

Pipeline Details

The PR security review pipeline:

  1. Gets changed files via git diff --name-only <base_ref> HEAD
  2. Queries methods in changed files from the CPG database (nodes_method)
  3. Runs SecurityScanner on each changed method (HEAD findings)
  4. Runs SecurityScanner on the same methods for the base ref (base findings)
  5. Computes “New vs Fixed vs Existing” delta via fingerprinting
  6. Counts findings by severity (critical, high, medium, low)
  7. Generates SARIF 2.1.0 output (via SARIFExporter) and PR comment markdown with delta

Autofix CLI

The --autofix flag on the audit command generates automated fix suggestions for security vulnerabilities found via taint analysis.

Usage

# Run security audit with autofix
python -m src.cli audit --db data/projects/postgres.duckdb --autofix

# JSON output for CI integration
python -m src.cli audit --db data/projects/postgres.duckdb --autofix --format json

When --autofix is enabled, the audit pipeline:

  1. Runs the standard 9-scenario security audit
  2. Extracts taint paths from security findings
  3. Calls AutofixEngine.generate_fixes() on each taint path
  4. Outputs diffs with confidence scores (does not apply patches)

Configuration

Autofix behavior is controlled via config.yaml:

autofix:
  enabled: true
  context_lines_before: 5
  context_lines_after: 5
  llm_max_confidence: 0.6
  llm_temperature: 0.1
  llm_max_tokens: 2048
  max_fixes_per_run: 10
  require_approval: true

REST API

POST /api/v1/security/autofix

Request body:

{
  "method_name": "exec_query",
  "cwe": "CWE-89",
  "source_path": "/path/to/source"
}

Returns an array of fix suggestions with diffs, confidence scores, and explanations. Read-only — never applies patches.

MCP Tool

The codegraph_autofix MCP tool provides autofix via the MCP protocol:

codegraph_autofix(method_name="exec_query", cwe="CWE-89")

Returns JSON with fix diffs (read-only, never applies).

See Also