This reference documents every command available in the gograph CLI, compiled directly from the production source code.

Indexing & Core Commands

build

gograph build [path] [--precise]

Walks and parses a Go repository. Generates the structured graph at .gograph/graph.json and nine targeted Markdown reports in .gograph/.

  • Arguments: path (optional, defaults to .)
  • Flags:
    • --precise: Enables type-checked Class Hierarchy Analysis (CHA) using Go’s type-checker to resolve dynamic interface dispatches to concrete caller/callee relationships. Slower, requires code to be compilable.

stale

gograph stale

Checks if any .go source files in the repository are newer than .gograph/graph.json. Returns a list of files that have been modified since the last build.

stats

gograph stats

Provides a zero-parse index health summary derived entirely from .gograph/graph.json. Extremely fast.

  • Output fields:
    • schema_version
    • generated_at
    • packages
    • files
    • symbols
    • calls
    • imports
    • routes
    • sqls
    • env_reads
    • test_edges

Search & Navigation

query

gograph query <term...>

Performs a broad, case-insensitive substring search across multiple entities.

  • Scans: Symbol names, file paths, package names, import paths, and call sites.
  • Logic: Performs OR-matching if multiple terms are provided.

focus

gograph focus <package>

Extracts targeted package orientation context.

  • Output: Returns all files, symbols, internal calls, and dependencies of the specified package.

node

gograph node <name>

Displays detailed AST metadata for a single named symbol, package, or file.

  • Output fields: Kind, file, line, signature, comments/docstrings, and struct fields.

source

gograph source <name>

Extracts the exact raw source code block for a symbol (function, method, struct, or interface) from the filesystem using the graph’s location data.

  • Note: This is the preferred way for AI agents to view symbol declarations and bodies, avoiding reading entire files.

Call Graph Commands

callers

gograph callers <function> [--no-tests] [--depth N]

Finds all callers of a target function or method.

  • Flags:
    • --no-tests: Filters out test files from caller results.
    • --depth N: Traverses the call graph upwards up to N hops (from 1 to 10). Useful for scoped neighborhood analysis. Defaults to 1 (direct callers).

callees

gograph callees <function> [--no-tests] [--depth N]

Finds all functions or methods called from within the target function.

  • Flags:
    • --no-tests: Filters out calls within test files.
    • --depth N: Traverses the call graph downwards up to N hops (from 1 to 10). Defaults to 1 (direct callees).

impact

gograph impact <symbol>
gograph impact --uncommitted
gograph impact --since <ref>

Calculates the transitive downstream blast radius (all functions that eventually call the target).

  • Options:
    • <symbol>: Performs impact analysis for a specific function.
    • --uncommitted: Computes the blast radius for all currently modified uncommitted symbols.
    • --since <ref>: Computes the blast radius for all symbols changed since the specified git reference (e.g., main, v1.4.50).

path

gograph path <from> <to>

Calculates and prints the shortest call chain (BFS path) between two symbols, verifying reachability.

orphans

gograph orphans

Finds dead code candidates. Runs a full BFS reachability analysis starting from the entry points (e.g., main, registered HTTP routes, and exported package APIs) to identify entirely unreachable functions.

Interfaces & Types

implementers

gograph implementers <interface> [--test-only]

Finds structs that implement the named interface (duck-typing).

  • Flags:
    • --test-only: Restricts results strictly to structs defined in test or mock files.

interfaces

gograph interfaces <struct>

Duck-type checker. Finds all interfaces in the codebase that the specified struct implements.

constructors

gograph constructors <struct>

Finds factory and constructor functions that return the named struct (e.g., NewClient, New*).

literals

gograph literals <struct>

Finds every place where the struct is initialized using a composite literal (StructName{...}). Essential to run before adding or removing a required field to know exactly which sites will break.

returnusage

gograph returnusage <function>

Traces how each caller handles the return values of the specified function.

  • Labels: discarded, assigned, partially_ignored, returned, or passed. Run this before refactoring signatures to find callers that silently ignore return values.

usages

gograph usages <type>

Finds every place where a named type appears in parameter/return lists, struct fields, or interface methods. Essential for tracing the impact of a type change.

schema

gograph schema <table>

Finds structs mapped to a database table or schema via struct tags (e.g. db:"...", gorm:"...").

globals

gograph globals <pkg>

Finds all package-level variables and constants, as well as functions that mutate them.

mocks

gograph mocks <interface>

Alias for implementers <interface> --test-only. Kept for compatibility.

fixtures

gograph fixtures <pkg>

Finds test helper structs and test functions within test files in a specific package.

Packages & Dependencies

deps

gograph deps <pkg> [--transitive]

Finds the direct import dependencies of a package.

  • Flags:
    • --transitive: Calculates the full transitive closure of package imports (BFS).

dependents

gograph dependents <pkg>

Finds all packages in the repository that import the specified package (the inverse of deps). Deduplicated by package. Highly recommended to run before package-level refactoring.

imports

gograph imports <pkg>

Finds all source files in the repository that import a specific external or internal import path.

public

gograph public <pkg>

Lists only the exported (public) API symbols (types, functions, variables, constants) of a package.

Extraction Commands

routes

gograph routes

Extracts all HTTP REST API routes found in the codebase (handles Gin, Chi, Echo, and net/http literals).

sql

gograph sql

Extracts and maps raw SQL string queries to the functions that execute them.

errors

gograph errors [--no-tests]

Lists custom error variables (declared using errors.New, fmt.Errorf, etc.) and panic statements mapped to their source locations.

envs

gograph envs [term]

Lists every os.Getenv or viper.Get* read in the codebase, with file and line. Optional substring filter by key name.

concurrency

gograph concurrency [term]

Maps goroutine spawns (go func), channel operations, mutex locks, WaitGroups, and sync.Once usage.

Composed Token Saver Commands

These compound commands are optimized for AI agent consumption to prevent sequential tool execution round-trips, significantly saving context tokens and reducing latency.

context

gograph context <symbol> [--limit N]
gograph context --uncommitted

Gathers all essential structural details for a symbol or uncommitted changes in a single call.

  • Output: Node AST details, exact source code, caller list, callee list, test list, and its calculated architectural role classification.
  • Flags:
    • --uncommitted: Bundles the full context for all currently uncommitted modified symbols into one response.

explain

gograph explain <symbol>

Synthesizes AST data into a rich, prompt-ready natural language prose narrative.

  • Output details: Symbol purpose, Prod vs. Test split, McCabe cyclomatic complexity rating, SQL queries used, Environment variables read, matching HTTP routes, interface satisfaction, and an opinionated role classification (e.g., HTTP handler, orchestrator, utility).

endpoint

gograph endpoint <route> [--depth N] [--json] [--include-tests]

Generates a complete vertical slice report for a single HTTP endpoint.

  • Inputs: Handler symbol name (always works), route path fragment (e.g. /users), or route pattern (POST /api/users).
  • Composes: Route definition + handler function + full downstream callee chain (BFS, default depth 5) + database SQL queries + env vars read.

errorflow

gograph errorflow <term> [--no-tests]

Traces the lifetime of an error up to the HTTP/entrypoint layer.

  • Algorithm: Resolves the error’s declaration site, return/wrapping locations (including %w format strings), and traverses the call graph upwards to find entry points.
  • Flags:
    • --no-tests: Excludes test-file callers from the trace.

trace

gograph trace <term> [--no-tests]

Alias for errorflow. Kept for compatibility.

plan

gograph plan <symbol> [--with-context]
gograph plan --uncommitted

Generates a comprehensive change-impact plan prior to editing.

  • Output: Affected callers, relevant tests to run after editing, and specific risks (SQL writes, environment reads, public API drift).
  • Flags:
    • --with-context: Inlines the complete context for every symbol listed in the plan, avoiding sequential lookup calls.
    • --uncommitted: Generates a joint change plan for all currently modified uncommitted symbols.

review

gograph review <symbol>
gograph review --uncommitted

Performs post-edit verification.

  • Output: Code changes, complexity drift, test coverage status, and a risk evaluation.

Code Quality & Verification

check

gograph check [--config]
gograph check --uncommitted
gograph check --since <ref>

Executes static policy checks against package boundaries, API drift, and test requirements.

  • Options:
    • --config: Custom checks using .gograph/checks.json.
    • --uncommitted: Restricts policy validation to uncommitted modified files.
    • --since <ref>: Validates changes introduced since a git reference.

gate

gograph gate

Enforces CI/CD quality gates. Reads the .gograph.yml configuration and fails the build (returns exit code > 0) if thresholds (e.g. cyclomatic complexity, orphan counts, test coverage ratios) are violated.

snapshot

gograph snapshot save <name>
gograph snapshot diff <name>
gograph snapshot list
gograph snapshot drop <name>

Architectural metric snapshots. Captures the current codebase metrics (symbol count, coupling, orphans) to allow comparison before/after a refactoring.

boundaries

gograph boundaries [--config]
gograph boundaries --create

Enforces package modularity boundaries.

  • Options:
    • --config: Evaluates package import relationships against boundaries.json.
    • --create: Autogenerates a starting boundaries.json mapping based on the current package architecture imports.

complexity

gograph complexity [symbol]

Displays McCabe cyclomatic complexity for all functions, sorted highest first. Optional substring filter by symbol name.

  • Labels: LOW (0-4), MEDIUM (5-9), HIGH (10-19), VERY HIGH (20+).

coupling

gograph coupling [package]

Calculates Fan-In, Fan-Out, and Instability metrics for all packages or a target package.

  • Formula: Instability = FanOut / (FanIn + FanOut). A value of 0 means extremely stable (nothing depends on external elements); 1 means fully unstable (pure consumer).

hotspot

gograph hotspot [--top N]

Identifies structural hotspots by ranking functions by their incoming call count (fan-in). Essential to identify high-risk parts of the codebase. Defaults to --top 10.

skeleton

gograph skeleton

Outputs the entire repository’s API signatures with their function/method bodies stripped. Useful for full structural orientation.

mutate

gograph mutate <field>

Finds every function or method that assigns a value to a specific struct field.

arity

gograph arity [--min N]

Finds functions with excessive parameter counts. Defaults to --min 5.

Agent Integration

capabilities

gograph capabilities

Prints the token-optimized AI agent cheat sheet detailing common workflows and commands. Useful for bootstrapping context in an LLM system prompt.

mcp

gograph mcp [path]

Starts a Model Context Protocol (MCP) server over stdio, exposing all gograph capabilities as native tools for integration with AI clients (e.g., Claude Code, Cursor).

  • Auto-Build: If .gograph/graph.json does not exist when starting, automatically triggers gograph build to ensure the server starts successfully.

add-claude-plugin

gograph add-claude-plugin

Installs the gograph MCP tool as a Claude plugin. Configures a smart PreToolUse hook in .git/hooks/ and sets up CLAUDE.md workspace rules.

hook-guard

gograph hook-guard

Called by the PreToolUse hook. Intercepts incoming agent tool calls over stdin. If it detects the agent executing a raw grep or find over Go symbol names, it blocks the tool call and instructs the agent to use gograph instead to prevent hallucination.