CLI Reference

All commands are available via kirograph or the short alias kg.

Setup

kirograph install                 # Wire up MCP + hooks + steering + CLI agent in .kiro/
kirograph init [path]             # Initialize .kirograph/ in a project
kirograph init --index            # Initialize and index immediately
kirograph uninit [path]           # Prompts to remove integration files and .kirograph/ data
kirograph uninit --force          # Remove everything without confirmation

kirograph uninstall is an alias for kirograph uninit.

Indexing

kirograph index [path]            # Full re-index of the project
kirograph index --force           # Force re-index all files (ignore hash cache)
kirograph sync [path]             # Incremental sync of changed files
kirograph sync --progress         # Per-file verbose progress output
kirograph sync --files a.ts b.ts  # Sync specific files only
kirograph sync-if-dirty [path]    # Sync only if a dirty marker is present
kirograph mark-dirty [path]       # Write a dirty marker for deferred sync

Status & Maintenance

kirograph status [path]           # Show index stats (files, symbols, edges, sync state)
kirograph unlock [path]           # Force-release a stale lock file
kirograph query <term>                    # Search symbols by name
kirograph query <term> --kind class       # Filter by kind
kirograph query <term> --limit 20         # Limit results (default: 10)

Supported kinds: function, method, class, struct, interface, trait, protocol, enum, type_alias, property, field, variable, constant, enum_member, parameter, import, export, route, component, file, module, namespace

File Structure

kirograph files [path]                     # Show indexed file tree
kirograph files --format flat              # Flat list
kirograph files --format grouped           # Grouped by language
kirograph files --filter src/components    # Filter by directory prefix
kirograph files --pattern "**/*.test.ts"   # Filter by glob pattern
kirograph files --max-depth 2              # Limit tree depth
kirograph files --no-metadata              # Hide language/symbol counts
kirograph files --json                     # Output as JSON

Context Building

kirograph context "fix checkout bug"
kirograph context "add user authentication" --format json
kirograph context "refactor payment service" --max-nodes 30
kirograph context "validate token" --no-code

Affected Tests

Find test files that depend on changed source files, useful in CI or pre-commit hooks.

kirograph affected src/utils.ts src/api.ts           # Pass files as arguments
git diff --name-only | kirograph affected --stdin     # Pipe from git diff
kirograph affected --stdin --json < changed.txt       # JSON output
kirograph affected src/auth.ts --filter "e2e/**"      # Custom test file glob
kirograph affected src/lib.ts --depth 3 --quiet       # Paths only, shallow traversal

Example CI integration:

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | kirograph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

Caveman Mode

kirograph caveman lite    # compact, still readable
kirograph caveman full    # fragments, no articles
kirograph caveman ultra   # maximum compression
kirograph caveman off     # back to normal
kirograph caveman         # show current mode

Architecture Analysis

kirograph architecture [path]              # Packages + layers + all deps
kirograph architecture --packages          # Packages section only
kirograph architecture --layers            # Layers section only
kirograph architecture --format json       # JSON output

kirograph package <name>                   # Inspect a package by name/path fragment
kirograph package auth                     # Partial match accepted
kirograph package src/auth --no-files      # Omit file list

kirograph coupling [path]                  # All packages, sorted by instability
kirograph coupling --sort ca               # Sort by afferent coupling
kirograph coupling --sort ce               # Sort by efferent coupling
kirograph coupling --package auth          # Detail view for one package
kirograph coupling --format json           # JSON output

Graph Insights

kirograph hotspots [path]             # Top 20 most-connected symbols
kirograph hotspots --limit 10         # Limit results
kirograph hotspots --format json      # JSON output

kirograph surprising [path]           # Top 20 surprising connections
kirograph surprising --limit 10       # Limit results

kirograph dead-code [path]            # Unexported symbols with zero incoming refs
kirograph dead-code --limit 20        # Limit results
kirograph dead-code --format json     # JSON output

kirograph path <from> <to>            # Shortest path between two symbols
kirograph path LoginController Pool   # Example
kirograph path A B --format json      # JSON output

Snapshots & Diff

kirograph snapshot save [label]       # Save current graph state
kirograph snapshot save pre-refactor  # Named snapshot
kirograph snapshot list               # List all saved snapshots
kirograph snapshot diff               # Diff current vs latest snapshot
kirograph snapshot diff pre-refactor  # Diff current vs named snapshot
kirograph snapshot diff --format full # Full added/removed symbol lists
kirograph snapshot diff --format json # JSON output

Export Dashboard

kirograph export                      # Generate interactive graph dashboard
kirograph export --open               # Open in browser immediately
kirograph export --output ./report    # Custom output directory