Graph-It-Live CLI Reference

July 2, 2026 · View on GitHub

The graph-it CLI gives you full access to the dependency analysis engine of Graph-It-Live — no VS Code required. Run it in CI pipelines, pre-commit hooks, shell scripts, or in any terminal.

Installation
Quick Start
Global Options
Output Formats
Commands
- graph-it (no arguments)
- scan
- summary
- explain
- path
- check
- trace
- query
- tool
- serve
- install
- update
MCP Tools Reference (via graph-it tool)
Advanced Analysis Workflows
Tool Count: CLI vs MCP

Installation

Prerequisite: Node.js v22 or higher.

Global install (recommended):

npm install -g @magic5644/graph-it-live

After installation, graph-it is available system-wide:

graph-it --version
graph-it --help

Without installing globally (via npx):

npx @magic5644/graph-it-live scan
npx @magic5644/graph-it-live serve

From VS Code extension:

If you have the VS Code extension installed, you can expose the bundled binary to your PATH with:

graph-it install     # adds graph-it to your system PATH

Quick Start

# 1. Go to your project root
cd /path/to/your/project

# 2. Index the workspace
graph-it scan

# 3. Get a workspace overview
graph-it summary

# 4. Analyze a specific file
graph-it summary src/main.ts

# 5. Find what depends on a file
graph-it tool find_referencing_files --filePath=$(pwd)/src/utils.ts

# 6. Scan for dead code
graph-it check

Global Options

These options are available for every command:

Option	Shorthand	Default	Description
`--workspace <path>`	`-w`	auto-detected from `cwd`	Root directory of the project to analyze
`--format <format>`	`-f`	`text`	Output format: `text`, `json`, `toon`, `markdown`, `mermaid`
`--help`	`-h`	—	Show help for the current command
`--version`	`-v`	—	Print the installed version

Workspace auto-detection: If --workspace is omitted, graph-it looks for a package.json, tsconfig.json, pyproject.toml, or Cargo.toml in the current directory and its ancestors.

# Explicit workspace
graph-it scan --workspace /abs/path/to/project

# Let it auto-detect from cwd
cd /path/to/project && graph-it scan

Output Formats

All analysis commands support multiple output formats via --format:

Format	Description	Best for
`text` (default)	Human-readable structured text	Terminal inspection
`json`	Standard JSON	Scripting, piping to `jq`
`toon`	Compact Token-Oriented Object Notation	AI consumption (30–60% token savings)
`markdown`	Data wrapped in a Markdown code block	Reports, documentation
`mermaid`	Mermaid flowchart diagram syntax	Architecture docs, README, Notion

Format availability per command:

Format	scan	summary	explain	path	check	trace	query	tool
`text`	✓	✓	✓	✓	✓	✓	✓	✓
`json`	✓	✓	✓	✓	✓	✓	✓	✓
`toon`	✓	✓	✓	✓	✓	✓	✓	✓
`markdown`	✓	✓	✓	✓	✓	✓	—	✓
`mermaid`	—	—	—	✓	—	✓	—	—

Examples:

graph-it summary src/app.ts --format json
graph-it path src/index.ts --format mermaid      # → paste in GitHub, Notion, VS Code Preview
graph-it check --format markdown                  # → paste in a PR description
graph-it summary --format toon                    # → feed to an LLM

Commands

graph-it (no arguments)

Launches interactive mode when invoked without a command in a TTY session.

graph-it [options]

Behavior:

If stdin is a TTY, starts the interactive REPL.
If stdin is not a TTY, interactive mode is not started. Use direct commands such as graph-it summary, graph-it trace, or graph-it check.
REPL session default output format is text unless changed with /format.

REPL slash commands

Command	Description
`/query`	Query the codebase with natural language (no quotes needed for multi-word questions)
`/wiki`	Generate a navigable markdown wiki from the call graph
`/trace`	Run trace flow for a selected file and optional symbol
`/path`	Set session workspace scope (directory)
`/file`	Set active file context for context-aware commands
`/check-dependencies`	Check incoming and outgoing dependencies
`/cycles`	List confirmed dependency cycles for a file
`/summary`	Summarize current file context or workspace
`/architecture`	Build workspace architecture graph
`/check`	Find unused exports
`/format`	Set preferred output format for the session
`/command`	Run a raw CLI command line inside REPL
`/export`	Export dependency graph as standalone HTML (vis.js). Optional `--output <path>` / `-o <path>`. Scope: active file context → workspace scope (set via `/path`) → full workspace
`/help`	Show REPL command help
`/quit`	Exit interactive mode

Post-result actions

After each result, the REPL supports contextual actions:

drill-down into current file/symbol context
export current structured result in another format
save current output to file
set default session format
run context-aware follow-up actions (for example dependency, cycle, trace, dead-code, or architecture follow-ups)

Session state

REPL session state is in-memory for the current invocation and tracks:

workspaceRoot
lastFile
lastSymbol
lastResult
lastCommandLine
preferredFormat
recentFiles (max 5, newest first)
tipCounter

Tips

The REPL tip system includes:

general rotating tips
command-step tips (for example trace/check-dependencies/cycles/result steps)
persona-tagged tips (role-oriented hints)

Save path safety

When saving from REPL:

writes are restricted to paths inside the workspace root
path checks are enforced using resolved/real paths
symlink targets are refused for overwrite

scan

Index (or re-index) the workspace. Must be run before other analysis commands on first use; subsequent commands index automatically if needed.

graph-it scan [options]

Options:

Option	Default	Description
`--workspace, -w`	auto-detected	Project root to index
`--format, -f`	`text`	Output format

What it does:

Walks the workspace and parses every source file
Builds a dependency graph in memory (import/export edges)
Constructs a reverse index for O(1) "who imports this?" lookups
Prints index statistics: files indexed, total edges, duration

Output (text):

Indexed 347 files, 1 824 edges in 3.2 s
  TypeScript: 284 files
  JavaScript: 63 files
  Cycles detected: 2

Examples:

graph-it scan
graph-it scan --workspace /path/to/project
graph-it scan --format json       # → { "files": 347, "edges": 1824, ... }

Tip: In CI, run graph-it scan as a warm-up step before chaining other commands.

summary

Print a workspace overview: index statistics plus (optionally) a codemap for a specific file.

graph-it summary [file] [options]

Arguments:

Argument	Description
`file` (optional)	Source file to generate a codemap for

Options:

Option	Default	Description
`--workspace, -w`	auto-detected	Project root
`--format, -f`	`text`	Output format

What it does (no file argument):

Prints overall statistics: files indexed, edges, cycles, index freshness.

What it does (with file argument):

Returns index statistics plus a structured codemap for the file:

Exported symbols
Internal symbols
Direct dependencies (files imported)
Dependents (files that import this one)
Call flow (intra-file symbol call order)
Cycle indicators

Output (text, with file):

=== Index Status ===
Files: 347   Edges: 1824   Cycles: 2

=== Codemap: src/Spider.ts ===
Exports:  Spider, SpiderOptions
Internals: crawlFile, resolveImport, visitNode
Deps:     Parser.ts, PathResolver.ts, Cache.ts
Dependents: SpiderBuilder.ts, extension.ts
Call flow: crawl → crawlFile → resolveImport → visitNode
Cycles:   none

Examples:

graph-it summary
graph-it summary src/api/router.ts
graph-it summary src/api/router.ts --format markdown   # paste in docs
graph-it summary src/api/router.ts --format toon       # feed to LLM

explain

Analyze the internal call hierarchy of a file — which functions call which, in what order, including recursive cycles.

graph-it explain <file> [options]

Arguments:

Argument	Description
`<file>`	Source file to analyze (absolute or relative to workspace root)

Options:

Option	Default	Description
`--workspace, -w`	auto-detected	Project root
`--format, -f`	`text`	Output format

What it does:

Uses AST analysis (Tree-sitter + ts-morph) to map every symbol in the file and construct a call graph:

Which symbols are exported vs. internal
Which functions/methods call each other
Entry points (symbols called by nobody internally)
Cycle detection (recursive calls)

Output (text):

File: src/mcp/mcpServer.ts

Entry points: initializeServer(), main()

initializeServer()
  └── registerAllTools()         [call #1]
  └── setupFileWatcher()         [call #2]
  └── startListening()           [call #3]
      └── handleToolCall()
          ├── validateWorkspace()
          └── invokeWorker()

Cycles: none

Examples:

graph-it explain src/mcp/mcpServer.ts
graph-it explain src/analyzer/Spider.ts --format json
graph-it explain src/extension/GraphProvider.ts --format markdown

Use case: Understand how data flows through a complex file before refactoring — without reading every line.

path

Crawl the full dependency graph starting from an entry file (BFS traversal) and display all reachable files with their dependency relationships.

graph-it path <file> [options]

Arguments:

Argument	Description
`<file>`	Entry file to start crawling from

Options:

Option	Default	Description
`--workspace, -w`	auto-detected	Project root
`--format, -f`	`text`	Output format (`mermaid` generates a flowchart)
`--maxDepth <N>`	unlimited	Maximum traversal depth

What it does:

Starting from <file>, follows all import edges recursively (BFS) and returns:

The complete list of reachable files
Direct dependency edges
Cycle detection (circular imports highlighted)
Depth at which each file is reached

Output (text):

src/index.ts (depth 0)
  → src/app.ts (depth 1)
  → src/config.ts (depth 1)
      → src/env.ts (depth 2)
      → src/constants.ts (depth 2)
  → src/router.ts (depth 1)
      → src/handlers/auth.ts (depth 2)
      → src/handlers/users.ts (depth 2)
          ⟲ src/app.ts [CYCLE]

Total: 8 files, 2 cycles

Output (mermaid):

graph LR
  src/index.ts --> src/app.ts
  src/index.ts --> src/config.ts
  src/config.ts --> src/env.ts
  src/config.ts --> src/constants.ts
  src/index.ts --> src/router.ts
  src/router.ts --> src/handlers/auth.ts
  src/router.ts --> src/handlers/users.ts
  src/handlers/users.ts -.->|CYCLE| src/app.ts

Examples:

graph-it path src/index.ts
graph-it path src/index.ts --maxDepth 3
graph-it path src/index.ts --format mermaid > architecture.md
graph-it path src/index.ts --format json | jq '.files | length'

Use case: Generate an architecture diagram in seconds. Pipe --format mermaid output directly into your README, Notion page, or Confluence doc.

check

Find unused exported symbols (dead code) — either workspace-wide, scoped to a directory, or for a single file.

graph-it check [target] [options]

Arguments:

Argument	Description
(none)	Scan the entire workspace for unused exports
`<directory>`	Scan a specific directory and its subdirectories
`<file>`	Check a single file for unused exported symbols

Options:

Option	Default	Description
`--workspace, -w`	auto-detected	Project root
`--format, -f`	`text`	Output format

What it does:

Combines the dependency graph with export analysis to find symbols that are exported but never imported anywhere in the project. Reports:

File path of the symbol
Symbol name and type (function, class, variable, type alias…)
Whether it is completely unreferenced or only referenced within the same file

Output (text, workspace-wide):

Dead code scan — 347 files analyzed

src/utils/legacy.ts
  ⚠  formatDate        [function]   — exported, never imported
  ⚠  LegacyConfig      [interface]  — exported, never imported

src/api/deprecated.ts
  ⚠  oldHandler        [function]   — exported, never imported

3 unused exports found across 2 files.

Output (text, single file):

Checking src/utils/helpers.ts

  ✓  formatDate        used in 4 files
  ✗  parseQueryString  not used anywhere
  ✓  clamp             used in 2 files

1 unused export found.

Examples:

# Workspace-wide dead code scan
graph-it check

# Scope to a directory
graph-it check src/utils/

# Single file check
graph-it check src/api/handlers.ts

# Output as JSON for scripting
graph-it check --format json | jq '[.[] | select(.unusedCount > 0)]'

# Output as Markdown for PR descriptions
graph-it check --format markdown > dead-code-report.md

Use case: Run graph-it check in a pre-commit hook or CI step to prevent dead code from accumulating.

trace

Trace the complete execution path from a starting symbol — following every function call recursively until leaf functions are reached.

graph-it trace <file>#<Symbol> [options]

Arguments:

Argument	Format	Description
`<file>#<Symbol>`	`path/to/file.ts#FunctionName`	Entry symbol (file path + `#` + symbol name)

Options:

Option	Default	Description
`--workspace, -w`	auto-detected	Project root
`--format, -f`	`text`	Output format (`mermaid` generates a call flowchart)
`--maxDepth <N>`	`10`	Maximum recursion depth

What it does:

Starting from the specified symbol, follows every outgoing call edge recursively (DFS) and returns a tree showing the complete execution flow:

Each function call with its file location
Call ordering (numbered edges)
Recursive calls / cycles detected and labelled

Output (text):

Trace: src/analyzer/Spider.ts#crawl

crawl (Spider.ts)
  ├─[1] ensureIndexed (runtime.ts)
  ├─[2] crawlFile (Spider.ts)
  │     ├─[1] parseImports (Parser.ts)
  │     │     └─[1] tokenize (lexer.ts)
  │     ├─[2] resolveImport (PathResolver.ts)
  │     └─[3] visitNode (Spider.ts)
  │           ⟲ crawlFile [CYCLE — recursive]
  └─[3] buildGraph (GraphBuilder.ts)

Depth reached: 4   Cycles: 1

Output (mermaid):

graph TD
  crawl --> ensureIndexed
  crawl --> crawlFile
  crawlFile --> parseImports
  parseImports --> tokenize
  crawlFile --> resolveImport
  crawlFile --> visitNode
  visitNode -.->|CYCLE| crawlFile
  crawl --> buildGraph

Examples:

graph-it trace src/index.ts#main
graph-it trace src/api.ts#handleRequest --format mermaid
graph-it trace src/Spider.ts#crawl --maxDepth 5
graph-it trace src/mcp/mcpServer.ts#initializeServer --format json

Use case: Before changing a function signature, run trace to see every downstream function that will be affected, all the way to leaf functions.

Answer a natural language question about the codebase using the call graph. When an LLM API key is configured the answer is synthesised by the model; otherwise a heuristic fallback is used and a warning is printed to stderr.

graph-it query "<question>" [options]

Arguments:

Argument	Description
`<question>`	Natural language question about the codebase (max 1024 characters)

Options:

Option	Default	Description
`--workspace, -w`	auto-detected	Project root
`--depth <N>`	`2`	BFS depth for call graph traversal (1–5)
`--token-budget <N>`	`4000`	Max tokens for the subgraph context (500–16000)
`--format <fmt>`	`text`	Output format: `text`, `json`, `toon`

LLM configuration (environment variables):

Variable	Description
`ANTHROPIC_API_KEY`	Use Anthropic (`claude-haiku-4-5`)
`OPENAI_API_KEY`	Use OpenAI-compatible provider
`OPENAI_BASE_URL`	Base URL for OpenAI-compatible endpoint
`OPENAI_MODEL`	Model name for OpenAI-compatible provider

When neither key is set, the command falls back to a heuristic analysis and prints a notice to stderr.

Examples:

graph-it query "how does Spider crawl files"
graph-it query "how does Spider crawl files" --format text
graph-it query "what calls CallGraphIndexer" --depth 3
graph-it query "explain the MCP server architecture" --token-budget 8000
graph-it query "what is the entry point for the CLI" --format json

Breaking change: CallGraphIndexer SCHEMA_VERSION was bumped from 2 to 3 alongside this feature. The index is automatically rebuilt on first use after upgrading.

wiki

Generate a navigable markdown wiki from the call graph. Creates one article per source file with hub scores, symbol lists, caller/callee cross-links, and a grouped index — all with relative links only (portable, can be committed to the repo).

graph-it wiki [options]

Options:

Option	Default	Description
`--output <dir>`	`wiki`	Output directory (relative to workspace root, or absolute)
`--top <N>`	`10`	Number of top hub files to list in the index (1–50)
`--format <fmt>`	`markdown`	Output summary format: `markdown`, `json`, `toon`
`--workspace, -w`	auto-detected	Project root

Examples:

graph-it wiki                                  # write to ./wiki/
graph-it wiki --output docs/wiki               # write to ./docs/wiki/
graph-it wiki --top 20 --format json           # JSON summary, top 20 hubs
graph-it wiki --output /tmp/preview            # absolute output path

Output structure:

wiki/
  index.md          # Grouped file index with hub scores
  articles/
    src_foo.ts.md   # One article per source file
    src_bar.ts.md
    ...

Each article contains:

Hub score (0–100, higher = more depended-upon)
Symbols (functions, classes, interfaces, types)
Called by (callers from other files)
Calls (callees in other files)
All internal links are relative — safe to commit and view on any OS

REPL equivalent: Use /wiki inside graph-it interactive mode. MCP equivalent: graphitlive_generate_wiki tool.

tool

Invoke any of the 22 MCP analysis tools directly from the terminal — full MCP parity without a running server.

graph-it tool <name> [--<param>=<value>...] [options]
graph-it tool --list
graph-it tool --args '<json>' <name>

Arguments:

Argument	Description
`<name>`	MCP tool name (see `--list`)
`--list`	Print all 22 available tools with one-line descriptions

Options:

Option	Default	Description
`--<param>=<value>`	—	Pass individual parameters directly
`--args '<json>'`	—	Pass all parameters as a JSON string
`--workspace, -w`	auto-detected	Project root
`--format, -f`	`text`	Output format

List all tools:

graph-it tool --list

Output:

Available MCP tools:

  analyze_dependencies           Show direct imports and exports of a file
  crawl_dependency_graph         Full dependency tree from an entry file (BFS)
  find_referencing_files         All files that import a given file
  expand_node                    Incrementally expand dependencies of a node
  parse_imports                  Raw import statements parsed from a file
  verify_dependency_usage        Check if an import is actually used in source
  resolve_module_path            Resolve a module specifier to its absolute path
  get_index_status               Current state of the dependency index
  invalidate_files               Flush cache entries for specific files
  rebuild_index                  Trigger a full index rebuild
  get_symbol_graph               Symbol-level call graph within a file
  find_unused_symbols            Detect dead/unused exported symbols
  get_symbol_dependents          All symbols that depend on a given symbol
  trace_function_execution       Full recursive call chain from a symbol
  get_symbol_callers             All callers of a symbol across the project
  analyze_breaking_changes       Detect breaking API changes between two versions
  get_impact_analysis            Full impact analysis of changing a file/symbol
  analyze_file_logic             Intra-file call hierarchy (AST-based)
  generate_codemap               AI-friendly structural overview of a file (TOON)
  query_call_graph               BFS callers/callees via the SQLite call graph index
  scan_dead_code                 Workspace-wide scan for unused exported symbols
  query_natural_language         Answer a natural language question about the codebase (LLM or heuristic)
  generate_wiki                  Generate a navigable markdown wiki from the call graph

Calling a tool with parameters:

# Using --param=value syntax
graph-it tool analyze_dependencies --filePath=/abs/path/to/file.ts

# Using --args JSON syntax (useful for complex/nested params)
graph-it tool --args '{"filePath":"/abs/path/to/file.ts"}' analyze_dependencies

# With format
graph-it tool get_symbol_callers --filePath=/abs/path/to/Spider.ts --symbolName=crawl --format json

Examples per tool:

# Index status
graph-it tool get_index_status

# Analyze direct imports/exports of a file
graph-it tool analyze_dependencies --filePath=$(pwd)/src/app.ts

# Full dependency graph from entry file (BFS)
graph-it tool crawl_dependency_graph --entryFile=$(pwd)/src/index.ts

# All files that import a given file
graph-it tool find_referencing_files --filePath=$(pwd)/src/utils.ts

# Check if an import is actually used in source code
graph-it tool verify_dependency_usage --filePath=$(pwd)/src/app.ts --dependency=lodash

# Resolve a module specifier to its absolute path
graph-it tool resolve_module_path --filePath=$(pwd)/src/app.ts --modulePath=./utils

# Symbol-level call graph within a file
graph-it tool get_symbol_graph --filePath=$(pwd)/src/Spider.ts

# Find all callers of a specific symbol across the project
graph-it tool get_symbol_callers --filePath=$(pwd)/src/Spider.ts --symbolName=crawl

# Find all symbols that depend on a specific symbol
graph-it tool get_symbol_dependents --filePath=$(pwd)/src/Spider.ts --symbolName=Spider

# Trace complete execution path from a symbol
graph-it tool trace_function_execution --filePath=$(pwd)/src/Spider.ts --symbolName=crawl

# Detect breaking API changes between two versions of a file
graph-it tool analyze_breaking_changes --filePath=$(pwd)/src/api.ts --newFilePath=$(pwd)/src/api.new.ts

# Full impact analysis of changing a file
graph-it tool get_impact_analysis --filePath=$(pwd)/src/utils.ts

# Generate AI-friendly codemap of a file
graph-it tool generate_codemap --filePath=$(pwd)/src/Spider.ts

# Intra-file call hierarchy
graph-it tool analyze_file_logic --filePath=$(pwd)/src/mcp/mcpServer.ts

# Cross-file call graph (BFS from a symbol)
graph-it tool query_call_graph --filePath=$(pwd)/src/Spider.ts --symbolName=crawl --depth=3

# Workspace-wide dead code scan
graph-it tool scan_dead_code

# Scoped dead code scan
graph-it tool scan_dead_code --scopePath=$(pwd)/src/utils/

# Detect unused exports in a single file
graph-it tool find_unused_symbols --filePath=$(pwd)/src/api.ts

# Force cache flush for a file after editing
graph-it tool invalidate_files --filePaths='["$(pwd)/src/api.ts"]'

# Full index rebuild
graph-it tool rebuild_index

# Expand a node incrementally
graph-it tool expand_node --filePath=$(pwd)/src/app.ts --depth=2

# Parse raw import statements (no path resolution)
graph-it tool parse_imports --filePath=$(pwd)/src/app.ts

serve

Start the MCP stdio server — enables any MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, Windsurf, etc.) to connect to Graph-It-Live without VS Code.

graph-it serve [options]

Options:

Option	Default	Description
`--workspace, -w`	auto-detected	Project root the server will analyze

What it does:

Launches the full 22-tool MCP server process on stdio. The server:

Accepts MCP JSON-RPC messages from stdin
Performs dependency analysis on the workspace
Returns results on stdout
Auto-invalidates the cache when files change (via chokidar, debounced 300 ms)

MCP client configuration:

# Claude Code CLI (adds to your Claude config)
claude mcp add graph-it -- graph-it serve

# VS Code / Cursor (.vscode/mcp.json or .cursor/mcp.json)
{
  "servers": {
    "graph-it-live": {
      "type": "stdio",
      "command": "graph-it",
      "args": ["serve"],
      "env": { "WORKSPACE_ROOT": "${workspaceFolder}" }
    }
  }
}

# Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)
{
  "mcpServers": {
    "graph-it-live": {
      "command": "graph-it",
      "args": ["serve"],
      "env": { "WORKSPACE_ROOT": "/path/to/your/project" }
    }
  }
}

Environment variables:

Variable	Default	Description
`WORKSPACE_ROOT`	`cwd`	Absolute path to project root
`EXCLUDE_NODE_MODULES`	`true`	Whether to skip `node_modules`
`MAX_DEPTH`	`50`	Maximum dependency depth

install

Symlink the graph-it binary into your system PATH so it can be invoked from any directory without npx.

graph-it install

Note: This is a VS Code extension convenience command. When using the npm global install, graph-it is already on your PATH.

update

Check npm for a newer version of @magic5644/graph-it-live and install it if one is available.

graph-it update

Requires an active internet connection and npm in PATH.

MCP Tools Reference (via `graph-it tool`)

The graph-it tool command provides direct access to all 21 analysis tools (the MCP server exposes 22 including set_workspace, which is server-management only and not needed in CLI context — see Tool Count: CLI vs MCP).

Tool Details

`analyze_dependencies`

What it returns: All direct import / require statements in a file, resolved to absolute paths, plus all exported symbols with their types.

graph-it tool analyze_dependencies --filePath=/abs/path/to/file.ts

Output fields: imports[], exports[], filePath, language

`crawl_dependency_graph`

What it returns: The full BFS dependency tree starting from an entry file — all reachable files, edges, cycle information, and depth data.

graph-it tool crawl_dependency_graph --entryFile=/abs/path/to/index.ts
graph-it tool crawl_dependency_graph --entryFile=/abs/path/to/index.ts --maxDepth=5

Output fields: nodes[], edges[], circularDependencies[], nodeCount, edgeCount

Each node in nodes[] includes:

hubScore (0–1): proportion of workspace files that import this node
communityId (0+): path-based functional cluster — 0 = isolated, 1+ = first non-umbrella subdirectory group (e.g. files under src/analyzer/ → same communityId)

`find_referencing_files`

What it returns: All files in the project that import the given file — an O(1) reverse lookup from the pre-built reverse index.

graph-it tool find_referencing_files --filePath=/abs/path/to/utils.ts

Output fields: referencingFiles[], count

`expand_node`

What it returns: The immediate dependencies (one level) of a node, useful for incremental graph exploration without re-crawling the full tree.

graph-it tool expand_node --filePath=/abs/path/to/app.ts --depth=1

Output fields: dependencies[], filePath

`parse_imports`

What it returns: Raw import statements parsed from the source file, without path resolution. Useful for inspecting import syntax and module specifiers directly.

graph-it tool parse_imports --filePath=/abs/path/to/app.ts

Output fields: imports[] (with source, specifiers[], type)

`verify_dependency_usage`

What it returns: Whether a specific imported module is actually referenced in the source code (i.e., is it a live import or an unused one).

graph-it tool verify_dependency_usage --filePath=/abs/path/to/app.ts --dependency=lodash

Output fields: isUsed (boolean), usageLocations[]

`resolve_module_path`

What it returns: The absolute filesystem path that a module specifier resolves to, applying TypeScript path aliases, Node.js resolution rules, and workspace configuration.

graph-it tool resolve_module_path --filePath=/abs/path/to/app.ts --modulePath=@/utils/helpers

Output fields: resolvedPath, exists (boolean)

`get_index_status`

What it returns: Current state of the in-memory dependency index — number of indexed files, edges, index freshness, and memory usage.

graph-it tool get_index_status

Output fields: files, edges, indexedAt, isStale

`invalidate_files`

What it does: Removes specific files from the in-memory cache, forcing them to be re-analyzed on next access. Use after programmatic file edits.

graph-it tool invalidate_files --filePaths='["/abs/path/to/file.ts"]'

`rebuild_index`

What it does: Drops and rebuilds the entire dependency index from scratch. Useful after large refactors or when the index is stale.

graph-it tool rebuild_index

`get_symbol_graph`

What it returns: Symbol-level dependencies within a single file — which functions, classes, and variables are defined, and which call which internally.

graph-it tool get_symbol_graph --filePath=/abs/path/to/Spider.ts

Output fields: symbols[], dependencies[], file

`find_unused_symbols`

What it returns: Exported symbols in a file that are never imported or referenced elsewhere in the project.

graph-it tool find_unused_symbols --filePath=/abs/path/to/api.ts

Output fields: unusedSymbols[], totalExports, unusedCount

`get_symbol_dependents`

What it returns: All symbols (across the entire project) that depend on a specific symbol — the reverse of get_symbol_graph.

graph-it tool get_symbol_dependents --filePath=/abs/path/to/Spider.ts --symbolName=Spider

Output fields: dependents[] (with file, symbolName, type)

`trace_function_execution`

What it returns: The complete recursive call chain from a starting symbol — DFS traversal following every outgoing call edge until leaf functions.

graph-it tool trace_function_execution --filePath=/abs/path/to/Spider.ts --symbolName=crawl
graph-it tool trace_function_execution --filePath=/abs/path/to/Spider.ts --symbolName=crawl --maxDepth=5

Output fields: callTree (nested), cycles[], maxDepth

`get_symbol_callers`

What it returns: All callers of a specific symbol across the entire project — an O(1) lookup from the pre-built reverse symbol index.

graph-it tool get_symbol_callers --filePath=/abs/path/to/Spider.ts --symbolName=crawl

Output fields: callers[] (with file, symbolName, line)

`analyze_breaking_changes`

What it returns: Whether changes to a file introduce breaking changes — altered function signatures, removed exports, changed parameter types — and which callers are affected.

graph-it tool analyze_breaking_changes --filePath=/abs/path/to/api.ts --newFilePath=/abs/path/to/api.new.ts

Output fields: breakingChanges[], affectedCallers[], severity

`get_impact_analysis`

What it returns: A full impact report for changing a file — combines find_referencing_files, get_symbol_callers, and analyze_breaking_changes into a single structured result.

graph-it tool get_impact_analysis --filePath=/abs/path/to/utils.ts

Output fields: referencingFiles[], symbolCallers[], breakingChanges[], totalImpact

`analyze_file_logic`

What it returns: Intra-file call hierarchy from AST analysis — entry points, call order, internal cycles, symbol types.

graph-it tool analyze_file_logic --filePath=/abs/path/to/mcpServer.ts

Output fields: symbols[], callEdges[], entryPoints[], cycles[]

`generate_codemap`

What it returns: A structured, AI-friendly overview of a file in a single call: exports, internals, dependencies, dependents, call flow, and cycles.

graph-it tool generate_codemap --filePath=/abs/path/to/Spider.ts --format toon

Output fields: exports[], internals[], dependencies[], dependents[], callFlow, cycles[]

Tip: Use --format toon to reduce token consumption by 30–60% when feeding this to an LLM.

`query_call_graph`

What it returns: BFS neighbourhood of callers and callees from a symbol, using the SQLite call graph index built by the Live Call Graph engine.

graph-it tool query_call_graph --filePath=/abs/path/to/Spider.ts --symbolName=crawl --depth=3

Output fields: nodes[], edges[], cycles[]

Note: Requires the call graph index to have been built (auto-triggered on first use or when the VS Code panel is opened).

`scan_dead_code`

What it returns: All unused exported symbols found across the entire workspace (or a scoped directory), combining dependency graph analysis with export tracking.

# Entire workspace
graph-it tool scan_dead_code

# Scoped to a directory
graph-it tool scan_dead_code --scopePath=/abs/path/to/src/utils/

Output fields: unusedSymbols[] (with file, symbol, type), totalScanned, unusedCount

`query_natural_language`

What it returns: A natural language answer to a question about the codebase, grounded in a call graph subgraph. When an LLM key is configured the model synthesises the answer; otherwise a heuristic summary is returned.

Parameters:

Parameter	Type	Default	Description
`question`	string	—	Natural language question (max 1024 characters)
`depth`	number	`2`	BFS depth for call graph traversal (1–5)
`tokenBudget`	number	`4000`	Max tokens for subgraph context (500–16000)
`fileFilter`	string	—	Glob pattern to restrict which files are included
`outputFormat`	string	`toon`	Subgraph format passed to the LLM: `toon` or `json`

graph-it tool query_natural_language --question="how does Spider crawl files"
graph-it tool query_natural_language --question="what calls CallGraphIndexer" --depth=3
graph-it tool query_natural_language --question="explain the MCP server" --tokenBudget=8000

LLM configuration:

ANTHROPIC_API_KEY → uses claude-haiku-4-5
OPENAI_API_KEY + OPENAI_BASE_URL + OPENAI_MODEL → uses OpenAI-compatible provider
No key set → heuristic fallback (warning printed to stderr)

Note: The LLM calling this tool performs the synthesis — the tool returns a structured subgraph that the model interprets.

`generate_wiki`

Generate a navigable markdown wiki from the call graph. One article per source file, hub scores, symbol lists, caller/callee cross-links, and a grouped index — all with relative links only.

Parameter	Type	Default	Description
`workspaceRoot`	string	configured workspace	Absolute path to workspace root
`outputDir`	string	`wiki`	Output directory for wiki files
`topHubsLimit`	number	`10`	Number of top hub files to list (1–50)
`response_format`	string	`json`	Output summary format: `json`, `markdown`, or `toon`

graph-it tool generate_wiki
graph-it tool generate_wiki --outputDir=docs/wiki
graph-it tool generate_wiki --topHubsLimit=20 --response_format=toon

Advanced Analysis Workflows

Pre-Refactor Safety Check

Before modifying a module, understand its full impact surface:

# 1. Find all files that import the module
graph-it tool find_referencing_files --filePath=$(pwd)/src/UserService.ts

# 2. Find all callers of the function you're changing
graph-it tool get_symbol_callers --filePath=$(pwd)/src/UserService.ts --symbolName=getUser

# 3. Detect if your new signature breaks anything
graph-it tool analyze_breaking_changes \
  --filePath=$(pwd)/src/UserService.ts \
  --newFilePath=$(pwd)/src/UserService.proposed.ts

# 4. Full combined impact report
graph-it tool get_impact_analysis --filePath=$(pwd)/src/UserService.ts

# 5. Trace the full execution tree from your entry point
graph-it trace src/UserService.ts#getUser --format mermaid

Dead Code Audit

Find and remove unreachable code safely:

# Workspace-wide scan (shows all unused exports)
graph-it check --format json > dead-code.json

# Count total unused exports
cat dead-code.json | jq '[.[].unusedCount] | add'

# Scope to a specific module
graph-it check src/utils/ --format markdown > utils-dead-code.md

# Single file audit
graph-it check src/api/handlers.ts

Architecture Documentation

Generate dependency diagrams and documentation automatically:

# Mermaid flowchart for the main entry point
graph-it path src/index.ts --format mermaid > docs/architecture.md

# Codemap for every file in a module (pipe through xargs)
find src/analyzer -name "*.ts" | xargs -I{} graph-it summary {} --format markdown >> docs/analyzer-reference.md

# AI-friendly overview of the whole project
graph-it summary --format toon > project-overview.toon

# Execution flow diagram for a critical function
graph-it trace src/mcp/mcpServer.ts#initializeServer --format mermaid > docs/server-flow.md

CI Integration

Run dependency checks in your CI pipeline:

#!/bin/bash
# .github/scripts/dependency-check.sh

set -euo pipefail

echo "=== Indexing workspace ==="
graph-it scan --workspace .

echo "=== Dead code check ==="
DEAD=$(graph-it check --format json | jq '[.[].unusedCount] | add // 0')
echo "Unused exports: $DEAD"
if [ "$DEAD" -gt 10 ]; then
  echo "⚠ Too many unused exports ($DEAD). Clean up dead code before merging."
  exit 1
fi

echo "=== Checking for circular dependencies ==="
CYCLES=$(graph-it tool get_index_status --format json | jq '.cycles // 0')
if [ "$CYCLES" -gt 0 ]; then
  echo "⚠ $CYCLES circular dependency/ies detected."
  graph-it path src/index.ts --format json | jq '.cycles[]'
fi

echo "✅ Dependency checks passed."

Piping & Scripting

Because all commands support --format json, the output integrates naturally with jq and shell pipelines:

# Find the 10 most-imported files in the project
graph-it scan --format json \
  | jq -r '.files[] | "\(.importedBy) \(.path)"' \
  | sort -rn | head -10

# List all TypeScript files with circular dependencies
graph-it tool crawl_dependency_graph --entryFile=$(pwd)/src/index.ts --format json \
  | jq -r '.cycles[] | .files[]' | sort -u

# Generate a report of all files that depend on a utility module
graph-it tool find_referencing_files \
  --filePath=$(pwd)/src/utils/format.ts \
  --format json | jq -r '.referencingFiles[]'

# Check if a specific import is unused in a file
graph-it tool verify_dependency_usage \
  --filePath=$(pwd)/src/app.ts \
  --dependency=lodash \
  --format json | jq '.isUsed'

Tool Count: CLI vs MCP

The CLI exposes 22 tools via graph-it tool --list, while the MCP server provides 23 tools in total. This is by design:

Context	Tool count	Notes
`graph-it tool --list`	22	All analysis tools
MCP server (`graph-it serve`)	23	Same 22 + `set_workspace`

The extra tool, set_workspace, is a server management tool — it tells a running MCP server instance which directory to analyze. In CLI context this is handled by the --workspace flag (or auto-detection from cwd), so it is intentionally excluded from the CLI tool list.

Summary: The CLI gives you 100% parity with the MCP analysis tools. set_workspace is the only tool that exists in MCP but not in the CLI, and it would be redundant there.