CLI Reference
All commands are available via kirograph or the short alias kg.
Setup
kirograph install # Wire up MCP + hooks + steering in .kiro/
kirograph install --target kiro # Same as above (explicit)
kirograph install --target claude # Wire up Claude Code MCP + project memory
kirograph install --target codex # Write Codex instructions and print MCP config
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
# Global Kiro hook library (~/.kirograph/hooks/)
kirograph hook save [path] # Save workspace .kiro/hooks/ to global store
kirograph hook save --all # Save all without prompting
kirograph hook import [path] # Import global hooks into workspace
kirograph hook import --all # Import all without prompting
kirograph hook list # List saved global hooksKiro install — global hook import: during interactive kirograph install --target kiro (no --yes), if ~/.kirograph/hooks/ is non-empty, the installer adds a Hooks step (after Agent Behavior, before Memory) asking whether to import global hooks (None, All, or Select specific hooks). Selected hooks are copied after bundled KiroGraph hooks are written. Use kirograph hook import for a standalone import outside install.
kirograph hook menus: interactive save / import use All / Select specific hooks / Cancel. Summaries print hook display names only; hook list shows display name and description.
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 syncStatus & Maintenance
kirograph status [path] # Show index stats (files, symbols, edges, frameworks)
kirograph unlock [path] # Force-release a stale lock fileSearch & Exploration
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 JSONContext 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-codeAffected 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 traversalExample CI integration:
#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | kirograph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
npx vitest run $AFFECTED
fiCaveman 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 modeShell Compression
kirograph compression off # disable hook (tool still available)
kirograph compression normal # balanced: removes noise, keeps structure
kirograph compression aggressive # more compact: groups by category
kirograph compression ultra # maximum compression: counts only
kirograph compression # show current levelToken Savings
kirograph gain # summary stats
kirograph gain --graph # ASCII graph (last 30 days)
kirograph gain --history # recent command history
kirograph gain --daily # day-by-day breakdown
kirograph gain --period week # filter by period
kirograph gain --json # JSON exportArchitecture 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 outputGraph 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 outputCode Health
kirograph module-api [path] # List exported symbols in a file or directory
kirograph module-api [path] --limit 50 # Max results (default: 50)
kirograph rename-preview <symbol> # Show all reference sites for a symbol before renaming
kirograph rename-preview <symbol> --limit 50
kirograph doc-coverage [path] # Find exported symbols missing docstrings
kirograph doc-coverage [path] --limit 50
kirograph god-class # Classes ranked by member count
kirograph god-class --limit 20
kirograph inheritance-depth # Find deepest inheritance chains
kirograph inheritance-depth --limit 20
kirograph recursion # Find recursive and mutually-recursive functions
kirograph recursion --limit 30
kirograph largest # Symbols ranked by lines of code
kirograph largest --limit 20
kirograph largest --kind function # Filter by symbol kind
kirograph rank # Symbols ranked by fan-in or fan-out
kirograph rank --by fan-in # Default metric
kirograph rank --by fan-out
kirograph rank --limit 20
kirograph distribution [path] # Symbol-kind breakdown per file or directory
kirograph distribution [path] --limit 30
kirograph annotations [decorator] # Decorator/attribute histogram
kirograph annotations [decorator] --limit 20
kirograph session start # Save current graph state as baseline
kirograph session end # Show what changed since baseline
kirograph unused-imports # Find import nodes with zero resolved downstream edges
kirograph unused-imports --limit 50
kirograph gini # Gini coefficient on LOC, fan-in, or fan-out
kirograph gini --metric loc # Default metric (0=equal, 1=total inequality)
kirograph gini --metric fan-in
kirograph gini --metric fan-out
kirograph dependency-depth # Longest import chains via topological sort
kirograph dependency-depth --limit 20
kirograph health [path] # Composite graph health score (0–10000)
kirograph dsm [path] # Design Structure Matrix between modules
kirograph dsm --limit 20 # Limit modules shown (default: all)
kirograph test-risk [path] # Risk-ranked functions (complexity × fan-in)
kirograph test-risk --limit 20 # Limit results (default: 20)
kirograph test-risk --threshold 5 # Only show risk score above this value
kirograph test-coverage [path] # Parse and show coverage files
kirograph test-coverage --sort uncovered # Sort by uncovered lines (default)
kirograph test-coverage --sort coverage # Sort by coverage percentage
kirograph test-coverage --limit 20 # Limit results (default: 20)Complexity
kirograph complexity # Rank functions by cyclomatic, cognitive, and maintainability index
kirograph complexity --limit 20
kirograph complexity --sort-by cyclomatic # Default sort metric
kirograph complexity --sort-by cognitive
kirograph complexity --sort-by maintainability
kirograph complexity --threshold 10 # Only show symbols above this value
kirograph simplify-scan # Quality scan: complexity, dead code, and LOC thresholds
kirograph simplify-scan --limit 20Edit Primitives
kirograph str-replace <file> <old> <new> # Replace a unique string anchor; fails on 0 or >1 matches
kirograph multi-replace <file> old1 new1 old2 new2 ... # Multiple replacements as all-or-nothing transaction
kirograph insert-at <file> <anchor> <content> # Insert content before anchor (default)
kirograph insert-at <file> <anchor> <content> --after # Insert after anchor
kirograph insert-at <file> <linenum> <content> --line # Treat anchor as line number
kirograph ast-rewrite <file> <pattern> <rewrite> # Structural rewrite via ast-grep (requires ast-grep on PATH)Git Context
kirograph diff-context # Changed symbols with callers/callees and affected tests
kirograph diff-context --staged # Use staged changes only
kirograph diff-context --ref main # Compare against git ref
kirograph commit-context # Structured summary of staged changes for commit messages
kirograph pr-context <base> [head] # Semantic diff between two git refs for PR descriptions
kirograph pr-context main # Diff main..HEAD
kirograph pr-context main feature/my-branch
kirograph changelog <ref1> <ref2> # Human-readable semantic diff between two refs
kirograph test-map # Map symbols to test files; detect uncovered symbols
kirograph test-map [symbol] # Focus on a specific symbol
kirograph test-map --limit 20
kirograph test-coverage [path] # Parse coverage files and correlate with graph
kirograph test-coverage --sort uncovered # Sort by uncovered lines (default)
kirograph test-coverage --sort coverage # Sort by coverage percentage
kirograph test-coverage --limit 20 # Limit results (default: 20)Bench
kirograph bench # Quick local token-efficiency benchmark
kirograph bench --quiet # Print final score only (no per-step output)Branch
Track multiple git branches and compare symbol graphs across them.
kirograph branch list # List all currently tracked branches
kirograph branch add [branchName] # Start tracking current branch (or named branch)
kirograph branch remove <branchName> # Stop tracking a branch
kirograph branch gc # Clean up DBs for git branches that no longer exist
kirograph branch diff <branchA> [branchB] # Diff symbols between two branches
# (branchB defaults to current branch if omitted)
kirograph branch search <query> <branch> # Search symbols within a specific branchDev Tools
kirograph monitor # Live-tail the MCP call log
kirograph monitor --lines 50 # Show last N lines before tailing (default: 20)
kirograph upgrade # Update KiroGraph to the latest published version
kirograph upgrade --dry-run # Print what would be upgraded without installing
kirograph cost [sessionDir] # Report tool usage from session transcripts
kirograph cost --last 5 # Only analyse the last N sessions (default: all)
kirograph cost --category search # Filter by tool categoryManifest & Doctor
kirograph manifest # Workspace manifest: packages, versions, deps, licenses
kirograph manifest --package <name> # Drill into a specific package
kirograph manifest --ecosystem npm # Filter by ecosystem (npm, cargo, go, python)
kirograph manifest --drift # Surface packages with conflicting versions
kirograph doctor # Check KiroGraph setup health
kirograph doctor --fix # Auto-fix fixable issuesSnapshots & 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 outputExport Dashboard
kirograph export build [path] # Generate .kirograph/export/{index.html,app.css,app.js}
kirograph export start [path] # Generate and open in browser
kirograph export build -o /tmp/myexport # Custom output directory
kirograph export build --include-contains # Include structural contains edgesMemory
# Search (hybrid FTS + vector)
kirograph mem search <query> # hybrid search
kirograph mem search <query> --kind error # filter by kind
kirograph mem search <query> --limit 5 # limit results
kirograph mem search <query> --format json # JSON output
# Store observations
kirograph mem store "decided to use idempotency keys for payments"
kirograph mem store "auth bug: token refresh missing" --kind error
kirograph mem store --kind decision < decision.txt # pipe from stdin
# Timeline
kirograph mem timeline # last 5 sessions
kirograph mem timeline --limit 10 # more sessions
kirograph mem timeline --session <id> # observations for specific session
kirograph mem timeline --format json
# Status
kirograph mem status # health dashboard
# Maintenance
kirograph mem prune [--older-than 90d] # cleanup old observations
kirograph mem reembed # re-embed all with current model
kirograph mem reembed --batch 50 # control batch size
kirograph mem lint # find stale links, model mismatch, orphans
kirograph mem export [--format jsonl|md] # export for backup/reading
kirograph mem import <file.jsonl> # restore from JSONL backup (deduplicates)Requires enableMemory: true in .kirograph/config.json.
Dashboard
When semanticEngine is set to qdrant or typesense:
kirograph dashboard start [path] # Start server and open dashboard
kirograph dashboard stop [path] # Stop the running engine serverDocumentation
# Table of contents
kirograph docs toc # whole project
kirograph docs toc README.md # single file
kirograph docs toc README.md --tree # nested tree structure
# Search
kirograph docs search "authentication"
kirograph docs search "config" --file docs/guide.md
# Retrieve a section
kirograph docs section "README.md::installation#1"
kirograph docs section "README.md::installation#1" --context
# Outline
kirograph docs outline docs/api.md
# Cross-references
kirograph docs refs "docs/auth.md::oauth/token-refresh#2"
# Maintenance
kirograph docs reindex # force full re-index
kirograph docs lint # health checks
kirograph docs reembed # re-embed with current modelRequires enableDocs: true in .kirograph/config.json.
Data
# List datasets
kirograph data list
# Describe schema
kirograph data describe tests-fixtures-users
kirograph data describe tests-fixtures-users --column email
# Query rows
kirograph data query orders --filter status:eq:shipped --limit 10
kirograph data query users --filter age:gt:18 --columns name,email
# Aggregate
kirograph data aggregate orders --group-by region --metric sum:amount
kirograph data aggregate users --group-by role --metric count:id --metric avg:age
# Search columns
kirograph data search orders "price"
# Join two datasets
kirograph data join users orders --left-col id --right-col user_id
# Correlations & quality
kirograph data correlations sales-data --threshold 0.5
kirograph data quality orders
# Maintenance
kirograph data index # incremental index
kirograph data reindex # force re-index all
kirograph data lint # validate integrityRequires enableData: true in .kirograph/config.json.
Security
kirograph security [path] # Vulnerability status overview
kirograph security --refresh-staleness # Re-query registries for latest versions first
kirograph security --fail-on affected # Exit 1 if any affected CVEs (for CI pipelines)Shows: total dependencies, vulnerabilities found, top-risk CVE, verdict breakdown, stale data warnings, staleness count. Warns when vulnerability data exceeds securityEnrichMaxAgeDays (default: 7 days).
kirograph vulns [path] # List all vulnerabilities (sorted by risk score)
kirograph vulns --severity critical # Filter by severity
kirograph vulns --verdict affected # Filter by reachability verdict
kirograph vulns --epss 0.5 # Filter by EPSS exploitation probability >= 0.5
kirograph vulns --sort risk|cvss|epss|name # Sort order (default: risk)
kirograph vulns --stale # Show staleness score alongside each CVE
kirograph vulns --group-by workspace # Group by source manifest directory (monorepos)
kirograph vulns --refresh # Refresh from vulnerability databases first
kirograph vulns --fail-on affected # Exit 1 if condition met (CI security gate)
kirograph vulns --fail-on critical # Exit 1 if any CVSS >= 9.0
kirograph vulns --fail-on epss=0.5 # Exit 1 if any EPSS >= 0.5
kirograph vulns --add CVE-2024-1234 --package lodash --version 4.17.20 # Register private CVE| Flag | Description |
|---|---|
--severity <level> | Filter: critical, high, medium, low |
--verdict <verdict> | Filter: affected, not_affected, under_investigation |
--epss <threshold> | Filter by EPSS exploitation probability >= threshold (0.0–1.0) |
--stale | Show staleness score of the dependency alongside each CVE |
--refresh | Trigger fresh enrichment from configured databases before listing |
--add <cveId> | Manually register a CVE (requires --package and --version) |
--package <name> | Package name for manual CVE registration |
--version <ver> | Package version for manual CVE registration |
kirograph reachability <target> [path] # Check reachability for a CVE or dependency
kirograph reachability CVE-2023-12345 # By CVE ID
kirograph reachability lodash # By package namekirograph licenses [path] # List all dependency licenses
kirograph licenses --policy # Show only policy violations
kirograph licenses --deny "GPL-*,AGPL-3.0" # Override deny list (comma-separated SPDX patterns)
kirograph licenses --warn "LGPL-*" # Override warn list
kirograph licenses --format jsonkirograph staleness [path] # Check freshness against registries
kirograph staleness --threshold 0.5 # Only show staleness_score >= 0.5
kirograph staleness --refresh # Re-query registries first
kirograph staleness --format jsonStaleness score 0.0–1.0: 0 = current, 1 = very stale. Supports npm, PyPI, crates.io, RubyGems, Packagist.
CVE Suppression
Mark CVEs as false positives or accepted risks. Suppressions are stored in .kirograph/security-suppressions.json and filtered from all command output.
kirograph vuln suppress CVE-2024-1234 # Suppress a CVE
kirograph vuln suppress CVE-2024-1234 --reason "not affected in our usage"
kirograph vuln suppress CVE-2024-1234 --expires 2026-12-31 # Auto-expire on date
kirograph vuln unsuppress CVE-2024-1234 # Remove suppression
kirograph vuln suppressions # List all active suppressions
kirograph vuln suppressions --format jsonkirograph sbom [path] # Export CycloneDX 1.5 SBOM to stdout
kirograph sbom --output sbom.json # Export to filekirograph vex [path] # Export CycloneDX 1.5 VEX to stdout
kirograph vex --output vex.json # Export to fileSecurity Dashboard
Generate a self-contained HTML dashboard with all security data: vulnerability triage, SBOM and VEX download, license compliance, and dependency staleness.
kirograph security export [path] # Generate .kirograph/security-export.html
kirograph security export --open # Generate and open immediately in browser
kirograph security export --output report.html # Custom output pathThe dashboard has 6 tabs: Overview (stat cards, verdict chart, top CVEs by EPSS×CVSS), Vulnerabilities (filterable table with EPSS badges and expandable call paths), SBOM (component list + one-click CycloneDX JSON download), VEX (analysis states + one-click download), Licenses (policy violations highlighted), Staleness (score bars, sortable table).
Requires enableSecurity: true in .kirograph/config.json.
Attack Surface
Map HTTP routes to reachable vulnerable dependencies. Shows route name, exposure level (public/authenticated/internal), hop count to vulnerable dependency, and risk score.
kirograph attack-surface [path] # Full attack surface report
kirograph attack-surface --public-only # Only public-facing routes
kirograph attack-surface --limit 10 # Limit number of routes shown
kirograph attack-surface --format json # JSON outputSecrets Detection
Scan for 14 secret types (AWS keys, GitHub tokens, database URLs, JWT secrets, etc.) enriched with call-graph blast radius — shows which entry points reach the file containing the secret.
kirograph security secrets [path] # Scan for secrets in the project
kirograph security secrets --include-tests # Include test files in the scan
kirograph security secrets --severity critical # Filter by severity
kirograph security secrets --format json # JSON outputSecurity Flows (SAST-lite)
Detect dangerous code patterns: SQL injection, dangerous eval/exec, unsafe deserialization, path traversal, and weak crypto. Each finding is tagged with an OWASP Top 10 (2021) category.
kirograph security flows [path] # Detect all security flow types
kirograph security flows --type sql # Filter to SQL injection only
kirograph security flows --format json # JSON outputSupported flow types: sql, eval, deserialization, path-traversal, crypto.
Pattern Search
AST structural pattern search using @ast-grep/napi. Requires enablePatterns: true in .kirograph/config.json and @ast-grep/napi installed. Only available when both conditions are met.
kirograph pattern 'eval($X)' # find all eval() calls
kirograph pattern 'eval($X)' --lang typescript # filter by language
kirograph pattern --list # browse bundled SAST rules
kirograph pattern --library sql-injection-concat-js # run a specific rule
kirograph pattern --format json # JSON output for CIExit codes: 0 = no findings, 1 = findings found (suitable for CI gates), 2 = @ast-grep/napi not installed or enablePatterns is false.
CI/CD Security Report
Generate a structured security report for CI/CD pipelines. Supports JSON, SARIF 2.1.0 (uploadable to the GitHub Security tab), or compact text format.
kirograph security ci-report [path] # Compact text report
kirograph security ci-report --format sarif --output results.sarif # SARIF for GitHub
kirograph security ci-report --format json # Machine-readable JSON
kirograph security ci-report --fail-on critical # Exit 1 if critical issues foundSupply Chain
Assess supply chain health: OpenSSF Scorecard scores, maintainer count, abandoned package detection (>365 days inactive), and new package risk (<30 days old).
kirograph supply-chain [path] # Full supply chain report
kirograph supply-chain --threshold high # Only show high or critical risk packages
kirograph supply-chain --refresh # Re-query external sources first
kirograph supply-chain --format json # JSON outputDependency Confusion
Detect dependency confusion attacks: internal packages whose names exist in public registries. Also detects typosquatting (Levenshtein distance ≤ 2 from popular package names).
kirograph dep-confusion [path] # Check for dependency confusion risks
kirograph dep-confusion --format json # JSON outputRemediation SLA
Track SLA compliance per CVE. Thresholds: critical=7 days, high=30 days, medium=90 days. Shows days open, days since fix became available, and SLA status (ok/warning/overdue).
kirograph remediation [path] # Full SLA report for all CVEs
kirograph remediation --overdue-only # Show only CVEs past their SLA deadline
kirograph remediation --format json # JSON outputRequires enableSecurity: true in .kirograph/config.json.