graph-sitter
Documentation menu

Parse Command

The parse command reads a local repository and prints graph summary counts for files, symbols, imports, exports, references, and dependencies.

graph-sitter parse .

Usage

graph-sitter parse [PATH] [OPTIONS]

PATH defaults to the current directory. The command does not require .codegen initialization or an active session.

Options

  • --backend python|rust|auto: Choose the graph backend. Defaults to python.
  • --fallback python|error: Choose fallback behavior when the Rust backend is unavailable. Defaults to error.
  • --language auto|python|typescript: Choose the repository language. Defaults to auto.
  • --format summary|json: Choose human-readable or machine-readable output. Defaults to summary.
  • --output FILE: Write JSON output to a file. Requires --format json.
  • --subdir PATH: Limit parsing to a repository-relative subdirectory or file. Pass this option more than once to include multiple paths.

JSON Output

Use JSON output in scripts, CI, and agent workflows:

graph-sitter parse . --language python --backend python --format json

The JSON payload includes the requested backend, actual backend, language, elapsed time, selected subdirectories, and graph count fields. It also includes schema_version; the current parse summary schema is version 1.

Write JSON to a file when the parse output is large or consumed by another tool:

graph-sitter parse . --language python --format json --output graph-sitter-index.json

--output is JSON-only. Human-readable summary output is always printed to stdout.

Subdirectory Parsing

Use --subdir to avoid parsing an entire large repository when the task is localized:

graph-sitter parse . --language python --subdir src --format json
graph-sitter parse . --language typescript --subdir packages/app --subdir packages/ui --format json

Subdirectory paths are resolved relative to PATH. Absolute paths are accepted only when they are inside the repository. Directory filters are passed into the same file-discovery path used by the Python and Rust backends.

Rust Backend

Use strict Rust mode for performance validation:

graph-sitter parse . --language python --backend rust --fallback error --format json

Use doctor first when validating a new installation:

graph-sitter doctor --backend rust --language python --json

Rust-backed parsing requires a package artifact that includes the graph_sitter_py extension. Until a release has passed the wheel and published-package checks, prefer branch-built wheel commands for Rust validation.

With uvx

Published package form:

uvx --python 3.13 graph-sitter parse . --language python --format json
uvx --python 3.13 graph-sitter parse . --language python --format json --output graph-sitter-index.json

Branch-built wheel validation form:

uvx --python 3.13 --from dist/<wheel>.whl graph-sitter parse . --language python --backend rust --fallback error --format json