graf

graf [--db PATH] [--json] command [args]

graf is a native Rust CLI that builds a persistent local graph of a codebase and its documents. It indexes definitions and relationships into SQLite (default .graf/index.db in the project, or the nearest ancestor database) so later searches query the store instead of reloading the whole graph into memory.Queries never refresh sources, fetch remotes, or call a model. graf update and graf watch are the explicit write paths: they re-extract only what changed, commit as one generation, and keep the previous graph if extraction fails. When two symbols could match, graf reports the ambiguity and source evidence instead of guessing; show, callers, callees, impact, and path accept exact node IDs.Static extractors cover many languages (Python, JavaScript/TypeScript, Rust, Go, C/C++, Java, and others) plus local documents such as Markdown, HTML, YAML, and text-bearing PDF. This is syntax-level extraction, not a compiler. Optional semantic providers, OCR, and transcription adapters exist but are off unless configured. Graf can also serve the graph over MCP, export snapshots, and migrate a Graphify `graph.json` with graf switch graphify.

--db PATH

Database path. Otherwise discover the nearest ancestor .graf/index.db.

Print machine-readable JSON instead of human-readable output.

Append read-command metadata to a JSONL file. --log-responses also records returned graph data.

Index supported source and documents (default path: .). Alias: extract.

Exclude local documents from discovery during index / add.

Re-extract local files for this invocation (also on update). Saved remote sources stay offline.

Include measured detection, extraction, and commit times in the report.

Refresh the native source root recorded in the database.

Compare local fingerprints without invoking models or converters.

Reclaim unused SQLite space. Does not read sources or change graph facts.

Foreground polling loop that runs update when fingerprints change (default 1000 ms). Not a service.

Find symbols and explore a bounded neighborhood (BFS by default).

Traversal depth 0–6 (query default 1, impact default 3, path default 6).

Maximum results 1–500 (default 100). Truncation is reported.

Edge direction for query (default both) and path (default out).

Filter by relation such as calls, imports, or contains. Repeatable on impact.

Restrict node kinds (repeatable). --file restricts source files.

Depth-first traversal instead of breadth-first.

Include edges between any returned nodes, within the query bounds.

Show an exact ID or unique symbol and its immediate neighbors. Alias: explain.

Immediate incoming calls.

Immediate outgoing calls.

Follow reverse dependencies from a symbol, class members, or source file. Alias: affected.

Find a bounded path between two nodes.

Graph-wide counts, coverage, and diagnostics.

Import a URL, Google pointer, or local document and keep its extracted facts.

Shallow-clone a GitHub repository under ~/.graf/repos/OWNER/REPO (or --output DIR). --refresh fetches and fast-forwards; local changes are never reset.

Import a Graphify snapshot into .graf/index.db and switch a supported project MCP connection. --undo reverses the switch.

Add or remove reversible agent guidance, skills, or MCP configuration (--platform, --project, --skill, --mcp).

Serve read-only MCP tools over stdin/stdout or explicit HTTP.

Import a graph snapshot into an empty database.

Write a complete snapshot (JSON, GraphML, Cypher, Mermaid, HTML, and others).

Opt into refreshing an existing index after Git commits and merges. Does not add the index to Git.

Queries never refresh the graph; run graf update (or watch) after editing source. Ambiguous names are errors—copy an exact node ID from query or stats. Extraction is static: dynamic dispatch, macros, and reassigned function pointers can stay unresolved. A drop in model-generated facts is refused unless --allow-semantic-shrink is set (a portable snapshot is saved under .graf/backups first). Keep .graf/index.db out of Git. Compaction can need temporary free space up to twice the database size. Git must be installed separately for clone.

graf is an independent Rust implementation inspired by Graphify. It stores the graph in SQLite so searches and incremental updates do not reload the whole graph. The crate is graf-cli; the installed binary is graf. Licensed under Apache-2.0.

ctags(1), cscope(1), ast-grep(1), rg(1), graphify-csharp(1)

Source code · Homepage · Documentation