CLI Reference

Assume the CLI is available as codegraph.

For a source checkout of this repo, replace codegraph with node ./dist/cli.js.

If the CLI is not installed yet, use the install paths in docs/installation.md. Do not use the unscoped codegraph package name.

Bare codegraph graph writes codegraph.json and codegraph.err in the current directory. Use --stdout, --output <path>, or an explicit format flag such as --json when scripting.

Runtime selection

The CLI defaults to --native auto, which uses the native Tree-sitter path when a compatible native artifact is available and falls back automatically otherwise.

--native on: require native explicitly and fail if it is unavailable
--native off: force the opt-in JS Tree-sitter fallback path for comparison and debugging when @lzehrung/codegraph-js-fallback is installed

Project config

Commands that scan a project read codegraph.config.json from --root when it exists. The current config surface is intentionally small:

{
  "discovery": {
    "includeGlobs": ["src/**/*.ts"],
    "ignoreGlobs": ["tests/samples/**"],
    "useGitignore": true
  }
}

discovery.includeGlobs and discovery.ignoreGlobs are project-root-relative, even when a command scans child include roots. discovery.ignoreGlobs is useful for large fixture, generated, or vendored folders that should not be indexed for search, unresolved-import checks, graphing, impact, or review. CLI --include-glob and --ignore-glob values are added for a single run; with child include roots, CLI globs stay relative to each scanned root. --no-gitignore overrides useGitignore.

Core commands

Dependency graphs

# First-pass repo summary and next-step suggestions
codegraph inspect ./src --limit 20

# Whole-repo graph
codegraph graph ./

# Default graph output to stdout
codegraph graph ./ --stdout

# Fast graph-only overview
codegraph graph ./src --fast-graph

# Full AST-based graph
codegraph graph ./src

# Build a dependency graph from multiple roots
codegraph graph ./src ./packages/app ./packages/lib --mermaid > graph.mmd

# Graph-first document and template edges also participate for HTML, Astro,
# Handlebars, Markdown, MDX, reStructuredText, and AsciiDoc local links,
# plus MDX and Astro static imports

# Narrow scanned files and exclude generated files while preserving .gitignore
codegraph graph --root . ./src --include-glob "**/*.ts" --ignore-glob "**/*.spec.ts" --json

# Disable .gitignore filtering when ignored or generated files are intentionally in scope
codegraph graph --root . ./src --no-gitignore --json

# Mermaid output
codegraph graph ./src --mermaid

# Detailed symbol graph
codegraph graph ./src --symbols-detailed --compact-json

# Include detailed SQL statement facts in JSON graph output
codegraph graph --root . --sql-artifacts --json

# SQLite export
codegraph graph --sqlite ./codegraph.sqlite

# Build and report diagnostics
codegraph graph --report
codegraph index --report
codegraph review --report --report-file review.report.json

Graph, index, and review reports include backend.native.byLanguage so native usage and fallback remain visible per language. Build reports also include backend.parser when syntax-tree backend degradation leaves files without parser context. Reports also include graph.fallbackImportExtraction.byLanguage and byReason when regex import extraction is used. Review JSON reports diagnostics.symbolMappingParseFailures, diagnostics.missingFiles, changedFiles[].status as updated, deleted, or missing, and sqlContext when changed SQL files or changed SQL literals make SQL artifact facts relevant.

Symbols, navigation, grep, and chunking

# Build the full project index
codegraph index

# Print full JSON index including locals, imports, and exports
codegraph index --json

# Use concurrency and incremental cache
codegraph index --threads 8 --cache disk

# Enable worker threads for parallel native extraction
codegraph index --workers --threads 8 --cache disk

# Search for agent-ready anchors across symbols, paths, chunks, SQL objects, and graph context
codegraph search "validate user" --json
codegraph search "public users" --mode sql --json
codegraph search "handle login" --from src/auth.ts --mode graph --depth 1 --json
codegraph search --help

# Explain a file, symbol, SQL object, or search result handle
codegraph explain src/auth.ts --json
codegraph explain validateUser --json
codegraph explain public.users --json
codegraph explain src/large-file.ts --max-symbols 25 --json
codegraph explain --help

# Build an agent-ready artifact bundle
codegraph artifact build --root . --out codegraph-out --json
codegraph artifact build --root . --out codegraph-out --sqlite --graph-json --report --questions --force --json
codegraph artifact --help

# Serve MCP tools over the same search, navigation, artifact, and review layer
codegraph mcp serve --root . --stdio
codegraph mcp serve --root . --artifact codegraph-out --stdio
codegraph mcp serve --root . --stdio --allow-build
codegraph mcp serve --root . --port 7331
codegraph mcp --help

# Chunk a file for LLM processing
codegraph chunk src/utils.js

# Output text chunks as JSON
codegraph chunk package.json --text --max-tokens 200

# Override language detection and token limits
codegraph chunk config.yaml --language yaml --min-tokens 100 --max-tokens 300

# Go to definition
codegraph goto <file> <line> <column>

# Find references
codegraph refs --file <file> --line <line> --col <column>
codegraph refs --file <file> --line <line> --col <column> --pretty

# Run a Tree-sitter query across the repo
codegraph grep --query '(function_declaration name: (identifier) @name)'

# Run a plain-text regex grep across the repo
codegraph grep --pattern 'eval\(' --ignore-case

search, explain, artifact, and mcp each support command-specific --help output so agents do not have to infer their options from the top-level help. search is deterministic and vectorless. It returns ranked results with project-relative stable handles, rank reasons, evidence, graph neighbors, follow-up commands, result counts, per-packet limits, and omission counts. explain resolves file paths, symbol names, SQL object names, and search handles, including file/chunk/graph handles, into bounded packets with symbols, dependencies, reverse dependencies, references, snippets, SQL object relation facts, changed-context review tasks/candidate tests, explicit limits, omission counts, and follow-ups. Generated follow-up and suggested-question commands POSIX-shell-quote dynamic arguments when needed. SQL object names resolve by exact name first; unqualified basenames resolve only when unique, so handles or schema-qualified names are preferred. Reference and snippet omission counts are lower bounds after the bounded navigation scan reaches its cap. artifact build writes codegraph.sqlite, self-describing project-relative graph.json, CODEGRAPH_REPORT.md, questions.json, and manifest.json by default; suggested questions use unique IDs backed by stable handles when a handle is available. Use artifact flags to select a subset. --force permits non-empty output directories, removes recognizable stale Codegraph artifacts, preserves unrelated operator files, and refuses unrecognized reserved-name collisions. Artifact contents exclude their own output directory and linked outside-root files. mcp serve exposes search, get_file, get_symbol, goto, refs, deps, rdeps, path, impact, review, query_sqlite, and artifact_build over stdio by default or Streamable HTTP with --port <number>. HTTP serves /mcp, binds to 127.0.0.1 unless --host <host> is passed, validates the Host header, allows loopback Host headers for wildcard binds, and rejects oversized request bodies. MCP file and artifact paths are confined to --root after realpath resolution; tools are read-only by default, query_sqlite is row- and byte-bounded and rejects synthetic payload functions, and --allow-build enables artifact output only. chunk uses semantic Tree-sitter chunking for registered source and stylesheet languages, Vue and Svelte block-aware chunking for single-file components, and text chunking for JSON, YAML, and unsupported extensions. Use --text to force text chunking.

Dependency analysis and diagnostics

# Dependencies of a file
codegraph deps src/main.ts

# Reverse dependencies
codegraph rdeps src/utils.ts

# Shortest dependency path
codegraph path src/main.ts src/utils.ts

# Cycle detection
codegraph cycles --sort priority

# Public API surface
codegraph apisurface

# Unresolved imports
codegraph unresolved

# Hotspots
codegraph hotspots ./src --limit 20

Cycle detection reports source dependency cycles. Document-only link loops, such as Markdown files linking to each other, remain in the graph for navigation but are not reported as dependency cycles.

Dependency read commands keep the same output contracts while using the indexed graph path and derived adjacency maps internally when available. This makes repeated deps, rdeps, and path reads cheaper on warm manifest-backed projects.

Impact, review, and graph delta

# Analyze PR impact from git history
codegraph impact --provider git --base main --head HEAD

# Analyze current staged and unstaged worktree changes against HEAD
codegraph impact --provider git --base HEAD --head WORKTREE

# Analyze the current index against HEAD
codegraph impact --provider git --base HEAD --head STAGED

# Analyze GitHub PR impact
codegraph impact --provider github --repo owner/name --pr 123

# Analyze raw diff text from stdin
cat diff.txt | codegraph impact --provider raw

# Pretty summary with severity scores
codegraph impact --base main --head feature --pretty

# Compact JSON using impact's graph-style alias
codegraph impact --base main --head feature --compact-json

# Limit analysis depth and reference count
codegraph impact --base main --head feature --depth 2 --max-refs 1000

# Exported-only scope
codegraph impact --base main --head feature --scope imported

# Ignore noisy files
codegraph impact --base main --head feature --ignore-glob "**/package-lock.json" "**/dist/**"

# Symbol references only
codegraph impact --base main --head feature --members-only

# Line context snippets for references
codegraph impact --base main --head feature --ref-context line

# Block context snippets for references
codegraph impact --base main --head feature --ref-context block --ref-block-max-lines 30

# Verify missing imports, exports, and declarations in changed lines
codegraph impact --base main --head feature --verify-refs

# Add LCOV and coverage-aware suggestions
codegraph impact --base main --head feature --lcov coverage/lcov.info --coverage-report coverage/coverage-final.json

# Use a repository-specific test command template
codegraph impact --base main --head feature --coverage-report coverage/coverage-final.json --test-command-template "pnpm vitest {files}"

# Review bundle for LLM-driven code review
codegraph review --base origin/main --head HEAD > review.json
codegraph review --base origin/main --head HEAD --include-symbol-details --max-callsites 5 > review.json
codegraph review --base origin/main --head HEAD --review-depth standard > review.json

# Compact human-readable review handoff
codegraph review --base origin/main --head HEAD --summary
codegraph review --base HEAD --head WORKTREE --summary

# File-level graph delta between revisions
codegraph graph-delta --git-base origin/main --git-head HEAD > graph-delta.json

For git-provider impact, --head accepts normal revisions plus worktree sentinels. Use WORKTREE to compare the base revision against the current working tree, including staged and unstaged tracked-file changes. Use STAGED or INDEX to compare the base revision against the current index; with --base HEAD, that is staged changes only. Untracked files are not included until they are staged or otherwise tracked by Git.

Impact JSON responses include schemaVersion plus format: "full" | "compact" so downstream tools can branch on payload shape without inferring it from missing fields. Use --compact or --compact-json for compact impact JSON. Impact JSON can also include exportSummary, reexportChains, topImpacts, surfaceArea, and clusters when applicable. File paths in impact reports are project-relative, and raw diffs that point outside the project root are rejected.

codegraph review --summary prints the changed-file count, changed-symbol count, risk summary, review tasks, and suggested tests without emitting the full projectFiles and symbol-detail JSON payload. High- and medium-confidence candidate tests are listed directly; low-confidence pattern matches are summarized as breadth hints and remain available in the full JSON bundle. Use plain review output when a downstream tool needs the complete structured bundle.

SQL review context is emitted only as sqlContext.entries[] in structured review JSON. Entries carry a reason such as changed_sql_file or changed_sql_literal, the matched objectName, and the original SQL statement fact. They are review hints, not source dependency edges.

inspect and unresolved exclude known runtime and package externals from unresolved-import counts so diagnostics stay focused on project resolution gaps. This includes Node builtins such as node:path and fs, supported-language standard library imports, URL imports, and dependencies declared in nearby manifests such as package.json, requirements.txt, requirements.in, pyproject.toml, setup.cfg, Pipfile, composer.json, Cargo.toml, go.mod, build.zig.zon, Gemfile, *.gemspec, pom.xml, build.gradle, build.gradle.kts, *.csproj, *.fsproj, *.vbproj, vcpkg.json, and Package.swift.

Doctor and skill commands

# Print the installed CLI version
codegraph version

# Print package identity as JSON
codegraph version --json

# Inspect package identity plus backend and runtime state
codegraph doctor

# Inspect one explicit graph or index artifact path
codegraph doctor ./.codegraph-cache/index-v1

# Inspect an artifact bundle directory or one artifact file
codegraph doctor ./codegraph-out
codegraph doctor ./codegraph-out/codegraph.sqlite

# Install the bundled skill into a known agent location.
# The installer creates the target skills directory as needed.
codegraph skill install --agent codex

codegraph skill install --agent claude

codegraph skill install --agent agents

codegraph skill install --agent cursor

codegraph skill install --agent gemini

codegraph skill install --agent opencode

# Install the bundled skill into an explicit target directory
# The target must end with /skills/codegraph.
codegraph skill install --target ~/.codex/skills/codegraph --force

# Inspect bundled skill paths and target health
codegraph skill doctor

codegraph skill install --agent <name> supports agents, codex, claude, cursor, gemini, and opencode. Skill install targets must end with skills/codegraph; when that safe target shape is satisfied, the installer creates the directory as needed. Cursor CLI now supports native skills directories too, so .cursor/skills/codegraph works alongside the universal ~/.agents/skills/codegraph location. codegraph version --json and codegraph doctor include the installed package name, version, and package root so local tarball or source-checkout installs can confirm which build the codegraph command is actually running. doctor also reports backend/runtime state and optional artifact details, including artifactBundle details for directories with a Codegraph manifest.json.

Incremental git-scoped runs

Use --changed-since <ref> or --git-base <ref> [--git-head <ref>] with graph and index to limit processing to the files reported by git diff.

The CLI pipes that file list into buildProjectIndexFromFiles, so unchanged files are skipped entirely when you are reviewing a PR.

--git-head accepts normal revisions plus the same worktree sentinels used by git-provider impact: WORKTREE compares the base revision to staged and unstaged tracked-file changes, while STAGED and INDEX compare the base revision to the current index.

SQLite schema and raw SQL

The SQLite export is a first-class query interface for agent workflows.

Tables

files(path TEXT PRIMARY KEY, is_external INTEGER)
symbols(id TEXT PRIMARY KEY, file TEXT, name TEXT, kind TEXT, docstring TEXT, line_span INTEGER, complexity INTEGER, visibility TEXT)
file_edges(from_path TEXT, to_path TEXT, to_type TEXT, raw TEXT, type_only INTEGER)
symbol_edges(from_id TEXT, to_id TEXT, label TEXT)
graph_metadata(key TEXT PRIMARY KEY, value TEXT)
graph_snapshots(id INTEGER PRIMARY KEY AUTOINCREMENT, created_at INTEGER, mode TEXT, changed_files INTEGER, deleted_files INTEGER, file_nodes INTEGER, file_edges INTEGER, symbol_nodes INTEGER, symbol_edges INTEGER)
graph_snapshot_files(snapshot_id INTEGER, file_path TEXT, change_kind TEXT)

Indexes

idx_symbols_name, idx_symbols_kind, idx_symbols_name_kind, idx_symbols_file_kind, idx_symbols_kind_complexity
idx_file_edges_from, idx_file_edges_to, idx_file_edges_type
idx_symbol_edges_from, idx_symbol_edges_to, idx_symbol_edges_label, idx_symbol_edges_label_to, idx_symbol_edges_label_from, idx_symbol_edges_label_from_to

Example SQL

SELECT s.name, s.file, COUNT(*) AS calls
FROM symbol_edges e
JOIN symbols s ON s.id = e.to_id
WHERE e.label = 'calls' AND s.kind = 'function'
GROUP BY s.id
ORDER BY calls DESC
LIMIT 20;

SELECT from_path
FROM file_edges
WHERE to_path = 'src/auth.ts' AND to_type = 'file';

Raw SQL access is intentionally read-only:

codegraph sql --db ./codegraph.sqlite --query "SELECT name, file FROM symbols WHERE kind = 'function' LIMIT 5;"

It accepts result-producing statements such as SELECT and PRAGMA and rejects mutating SQL.

Review bundle shape

codegraph review reuses the incremental manifest and produces a JSON bundle optimized for LLM-driven reviews.

{
  "schemaVersion": 2,
  "status": "ok",
  "summary": {
    "filesChanged": 3,
    "symbolsChanged": 12,
    "candidateTests": 5,
  },
  "riskSummary": {
    "level": "medium",
    "score": 60,
    "signals": ["exported-symbols-changed"],
  },
  "reviewTasks": [
    {
      "id": "review-summary",
      "title": "Review changed symbols",
      "description": "Scan the changed symbols and confirm behavioral changes align with intent.",
      "priority": "medium",
      "reason": "baseline-review",
    },
  ],
  "changedFiles": [
    {
      "file": "src/foo.ts",
      "status": "updated",
    },
  ],
  "graphDelta": [
    {
      "from": "src/foo.ts",
      "to": { "type": "file", "path": "src/bar.ts" },
      "raw": "./bar",
    },
  ],
  "candidateTests": [
    {
      "file": "tests/foo.test.ts",
      "confidence": "high",
      "reason": "importsChanged",
    },
  ],
  "diagnostics": {
    "missingFiles": [],
    "symbolMappingParseFailures": [],
  },
}

Important review-bundle details:

schemaVersion identifies the review JSON schema for CI validation and compatibility checks.
riskSummary and reviewTasks provide agent-ready review focus areas and likely risk hotspots.
changedFiles[].status distinguishes normal updates from real Git deletions and explicit missing input files.
diagnostics.symbolMappingParseFailures reports files where symbol-level diff mapping degraded. Source-language failures affect symbol-mapping-degraded risk; graph-first document files remain diagnostics without becoming high-priority source review tasks.
diagnostics.missingFiles reports explicit paths that were not present on disk.
graph-delta reports file-level edge additions and removals for changed files and is intended for lightweight CI artifacts.
--include-symbol-details attaches definition snippets and callsite ranges for changed symbols.
When diff data is available, review reports focus on symbols touched by diff hunks and include diffSnippets with changed-line context.
--review-depth minimal|standard|deep applies preset bundles:
- minimal: fast graph, no symbol snippets, maxCallsites=0, maxCandidates=10
- standard: symbol snippets plus up to 2 callsites, maxCandidates=25
- deep: symbol snippets plus up to 10 callsites, maxCandidates=50
Explicit flags like --include-symbol-details, --max-callsites, --max-tests, or --fast-graph override preset defaults.
For review accuracy, keep full parsing enabled unless you intentionally want a faster, less complete pass.
--incremental-strict disables fast graph extraction for changed files while still using incremental file selection.
--cache-verify validates the manifest before reuse and falls back to a full rebuild if mismatches are detected.

Local development

If you are working on this package itself, use tsx to run the source entrypoint directly:

npx tsx src/cli.ts graph
npx tsx src/cli.ts graph --fast-graph
npx tsx src/cli.ts goto <file> <line> <column>

Output formats

--pretty and --summary are presentation modes. They are intentionally compact and may omit low-confidence or verbose context that remains available in structured JSON and TypeScript return values. Integrators that compose deterministic review packs should use the exported TypeScript functions or JSON output.

Plain graph output is a file dependency graph only. In default graph mode, output goes to codegraph.json unless --stdout or --output <path> is passed.

{
  "nodes": ["/abs/path/a.ts", "..."],
  "edges": [
    {
      "from": "/abs/path/a.ts",
      "to": { "type": "external", "name": "react" },
      "raw": "react"
    },
    {
      "from": "/abs/path/a.ts",
      "to": { "type": "file", "path": "/abs/path/b.ts" },
      "raw": "./b"
    }
  ]
}

SQL files are part of normal graph output: .sql files are discovered by default, SQL-to-SQL object references appear as file edges, and SQL object symbols work with goto and refs inside SQL files. SQL-to-SQL edges are precise for exact object-name matches, heuristic for unambiguous qualified-to-basename fallback matches, and skipped for ambiguous basename guesses. SQL goto and refs resolve schema-qualified names plus object-level alias/table-qualified references such as t.id or schema.table.id to table/view definitions, not to column declarations. With --sql-artifacts, JSON graph output also includes detailed SQL statement facts and object-candidate metadata. SQL artifact nodes use sql_statement_fact and sql_schema_candidate truth tiers; they do not assert a current schema and do not globally link application-code strings to SQL objects.

Format notes:

Use --mermaid for a Mermaid flowchart.
Use --dot for Graphviz DOT.
In DOT output, type-only edges are dotted and external nodes are dashed ellipses.
Use --fast-graph for faster JS and TS specifier extraction.

When using --symbols:

Mermaid and DOT output include file nodes, file-to-file edges, symbol nodes, file-to-symbol containment edges, and symbol-to-symbol import edges.
Use --symbols-only to omit file nodes and edges and render symbols only.

When using --symbols-detailed:

Codegraph adds symbol-to-symbol uses edges when a symbol body references another symbol through local references, named or default imports, or namespace members.
You can combine --symbols-detailed with --symbols to keep both usage and import edges alongside file nodes.
Pruning options for large repos:
- --symbols-detailed-scope {all|imported}
- --symbols-detailed-max-edges N
- --symbols-detailed-members-only

Compact JSON replaces repeated file and symbol IDs with numeric indices:

codegraph graph --root . ./src --symbols-detailed --compact-json --output graph.json

When targeting a different repo, pass it with --root rather than as an extra positional path:

codegraph graph --root /path/to/project --json --symbols-detailed --compact-json --output graph.json

Graph viewer

Use the Sigma-based viewer to interactively explore graph --json or graph --compact-json output:

# 1) Produce graph data
codegraph graph --root . ./src --compact-json --output codegraph.json

# 2) Serve the repo root and open the viewer
python3 -m http.server 4173
# open http://localhost:4173/docs/graph-visualization/

# optional
npm run visualizer:start

Viewer features:

renders file dependency graphs with Sigma.js
supports both default JSON and compact JSON graph payloads
supports optional symbol-node rendering for compact JSON payloads

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI Reference

Runtime selection

Project config

Core commands

Dependency graphs

Symbols, navigation, grep, and chunking

Dependency analysis and diagnostics

Impact, review, and graph delta

Doctor and skill commands

Incremental git-scoped runs

SQLite schema and raw SQL

Tables

Indexes

Example SQL

Review bundle shape

Local development

Output formats

Graph viewer

Related docs

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

Runtime selection

Project config

Core commands

Dependency graphs

Symbols, navigation, grep, and chunking

Dependency analysis and diagnostics

Impact, review, and graph delta

Doctor and skill commands

Incremental git-scoped runs

SQLite schema and raw SQL

Tables

Indexes

Example SQL

Review bundle shape

Local development

Output formats

Graph viewer

Related docs