Homeuvx graph-sitter

CLI reference for graph-aware agents.

Use the command line to parse repositories, inspect symbols, trace call relationships, and run focused codemods without writing a one-off script first.

terminal

$ uvx graph-sitter parse ./repo --format json$ uvx graph-sitter query-server start ./repo --backend rust --fallback error$ uvx graph-sitter query-server run ./repo --request '{"op":"symbols","query":"runInference"}'$ printf '{"id":"1","op":"symbols","query":"runInference"}\n{"id":"2","op":"exit"}\n' | uvx graph-sitter query ./repo$ uvx graph-sitter symbols runInference ./repo --backend rust$ uvx graph-sitter callgraph src/app.ts.main ./repo --depth 2$ uvx graph-sitter rename src/app.py:helper ./repo --to execute_helper --check

inspect

graph-sitter inspect FILE [PATH]

Shows line counts, imports, classes, functions, and per-function call summaries for a file.

uvx graph-sitter inspect packages/app/src/index.ts ./repo --level calls

symbols

graph-sitter symbols [QUERY] [PATH]

Finds functions, classes, and symbols and prints copyable target strings for later commands.

uvx graph-sitter symbols runInference ./repo --kind function --backend rust

query

graph-sitter query [PATH]

Parses once, keeps the graph in memory, and answers JSONL graph queries over stdin/stdout.

printf '{"id":"1","op":"symbols","query":"runInference"}\n' | uvx graph-sitter query ./repo

query-server

graph-sitter query-server start [PATH]

Starts a local background graph server so agents can query the same in-memory graph across shell commands.

uvx graph-sitter query-server run ./repo --request '{"op":"symbols","query":"runInference"}'

callgraph

graph-sitter callgraph TARGET [PATH]

Traces outbound callees or inbound callers with clean local, resolved, deduped edges by default.

uvx graph-sitter callgraph packages/app/src/index.ts.main ./repo --depth 2

using

graph-sitter using TARGET [PATH]

Traces the functions and methods a target calls, recursively up to the requested depth.

uvx graph-sitter using src/app.py:handler ./repo --depth 3 --resolved-only

usages

graph-sitter usages TARGET [PATH]

Finds callers and usage sites for a target, with optional recursive inbound traversal.

uvx graph-sitter usages src/app.py:helper ./repo --depth 2 --dedupe

rename

graph-sitter rename TARGET --to NAME [PATH]

Applies a graph-aware rename and reports affected files in check mode before writing.

uvx graph-sitter rename src/app.py:helper ./repo --to execute_helper --check

Common parse controls

These options are shared by the graph commands and make the CLI useful on large monorepos.

--backend python|rust|autoSelect the graph backend.

--fallback python|errorControl behavior when Rust is unavailable.

--language auto|python|typescriptSet language detection explicitly.

--subdir PATHLimit parsing to one or more repo-relative paths.

--format summary|jsonChoose human-readable or machine-readable output.

Persistent query sessions

Use query mode when an agent needs several graph lookups from the same repository. The command emits a ready event after the initial parse, then returns one JSON response per JSON request.

terminal

$ {"id":"symbols","op":"symbols","query":"runInference","kind":"function"}}$ {"id":"trace","op":"callgraph","target":"packages/app/src/index.ts.runInference","depth":2}}$ {"id":"done","op":"exit"}}

Background query server

Use server mode when a coding agent needs to query, edit files, then query again from separate shell commands. Client requests reload automatically when the repository has changed since the server parsed it.

terminal

$ uvx graph-sitter query-server start ./repo --language typescript --backend rust --fallback error$ uvx graph-sitter query-server run ./repo --request '{"op":"symbols","query":"runInference","kind":"function"}'$ uvx graph-sitter query-server run ./repo --request '{"op":"callgraph","target":"packages/app/src/index.ts.runInference","depth":2}'$ uvx graph-sitter query-server status ./repo$ uvx graph-sitter query-server stop ./repo

Full-repo TypeScript

Use the Rust backend for broad discovery and outbound call graph traversal. Scope to a package with the Python backend when you need function-level inbound caller recursion.

terminal

$ uvx graph-sitter parse ./monorepo --language typescript --backend rust --fallback error --format json$ uvx graph-sitter callgraph packages/app/src/index.ts.main ./monorepo --language typescript --backend rust --depth 2$ uvx graph-sitter usages packages/app/src/index.ts.main ./monorepo --language typescript --backend python --subdir packages/app