CLI Reference
Complete documentation for all Vokt CLI commands
vokt analyze
Run full call graph analysis
Runs the complete analysis pipeline: detects language(s), invokes the appropriate analysis engine(s), builds the call graph, extracts behavioral facts, computes graph metrics, and persists results. Requires the project to compile.
Usage
vokt analyze [--dir <path>] [--lang go|java|auto] [--algorithm pta|cha|rta]
[--di-mode spring|guice|none] [--no-tests] [--verbose]Flags
| Flag | Description |
|---|---|
| --dir <path> | Project directory (default: current directory) |
| --lang go|java|auto | Language to analyze. auto detects from project files (default: auto) |
| --algorithm pta|cha|rta | Analysis algorithm. pta (pointer analysis / VTA for Go) is default. cha is faster but less precise. rta requires main packages. |
| --di-mode spring|guice|none | Dependency injection framework to model. Injects synthetic call graph edges for DI wiring (default: none) |
| --no-tests | Exclude test functions from analysis (default: true) |
| --verbose | Show detailed analysis progress |
Examples
# Auto-detect language and run analysis vokt analyze # Analyze a Go repository vokt analyze --lang go # Analyze a Spring Boot project with DI resolution vokt analyze --lang java --di-mode spring # Use CHA for faster but less precise analysis vokt analyze --algorithm cha
vokt diff
Compare behavioral changes between commits
Compares analysis results between two commits and produces structural diffs with semantic drift events. Shows per-field changes to guards, mutations, and error paths with severity scoring. Requires vokt analyze to have been run on both commits.
Usage
vokt diff [--base <commit>] [--head <commit>] [--min-severity minor|moderate|major|critical]
[--fail-on <severity>] [--format json|sarif|md|viewer]Flags
| Flag | Description |
|---|---|
| --base <commit> | Base commit to compare against (default: main branch) |
| --head <commit> | Head commit to compare (default: current HEAD) |
| --min-severity <level> | Only show changes at or above this severity level |
| --fail-on <severity> | Exit non-zero if any change meets or exceeds this severity. Use in CI pipelines. |
| --format json|sarif|md|viewer | Output format (default: viewer) |
Examples
# Compare current branch against main vokt diff --base main # Show only major and critical changes vokt diff --min-severity major # Fail CI on critical changes vokt diff --fail-on critical # Output as JSON for CI integration vokt diff --format json
Example Output
PaymentService.processPayment (BEHAVIOR CHANGED): - removed guard: amount > 0 + added mutation: auditLog.write() Severity: CRITICAL — guard removed Blast radius (conservative): 23 (weighted: 31.4) OrderService.createOrder (BEHAVIOR CHANGED): + added call: inventoryService.reserve() Severity: MAJOR — new side effect Blast radius (conservative): 12 (weighted: 18.7) Summary: 2 behavioral changes, 14 safe refactors Guards: 1 removed Mutations: 1 added Calls: 1 added Max severity: CRITICAL
vokt risk
Show risk-ranked functions with transparent scoring
Displays functions ranked by composite risk score (0-100). Every score shows its component breakdown — blast radius, hub centrality, diff severity, churn rate, bus factor, propagation depth, and co-change anomaly — along with a reliability rating.
Usage
vokt risk [--pr] [--top <n>] [--sort risk|blast|hub] [--module <prefix>]
[--format json|md|viewer]Flags
| Flag | Description |
|---|---|
| --pr | Restrict to functions changed in the current PR |
| --top <n> | Show top N functions (default: 20) |
| --sort risk|blast|hub | Sort by risk score, blast radius, or hub centrality (default: risk) |
| --module <prefix> | Filter to a specific module or package prefix |
| --format json|md|viewer | Output format (default: viewer) |
Examples
# Show top 10 riskiest functions vokt risk --top 10 # Show risk for functions changed in this PR vokt risk --pr # Sort by blast radius instead of risk score vokt risk --sort blast # Filter to payment module vokt risk --module pkg/payment
Example Output
Risk Score: 78 (MEDIUM reliability) ├── Blast Radius: 88 (weighted: 31.4, conservative: 23) ├── Hub Centrality: 91 (23 callers, betweenness: 0.91) ├── Churn Rate: 72 (2.3 commits/week over 90 days) ├── Bus Factor: 65 (2 distinct authors) ├── Complexity: 45 (CC=8, nesting=4) └── Co-change: 40 (3 hidden coupling pairs) Reliability: MEDIUM — 21% of blast zone edges are DI synthetic.
vokt hub
Surface architectural hub functions
Shows hub functions ranked by betweenness centrality score. Distinguishes architecturally significant hubs (auth, payment, validation) from utility functions (loggers, formatters, error wrappers) using behavioral substance analysis.
Usage
vokt hub [--top <n>] [--min-callers <n>] [--format json|md|viewer]
Flags
| Flag | Description |
|---|---|
| --top <n> | Show top N hub functions (default: 20) |
| --min-callers <n> | Minimum caller count to include (default: 5) |
| --format json|md|viewer | Output format (default: viewer) |
Examples
# Show top 10 hub functions vokt hub --top 10 # Show hubs with at least 20 callers vokt hub --min-callers 20
Example Output
# Function Callers Hub Score Type 1 auth.ValidateToken 47 0.94 architectural 2 payment.ProcessPayment 23 0.91 architectural 3 repo.Save 38 0.87 architectural 4 logger.Info 92 0.82 utility [dampened] 5 errors.Wrap 64 0.71 utility [dampened]
vokt blast
Show confidence-weighted blast radius
Shows the blast radius for a specific function — how many callers are affected if this function's behavior changes. Displays conservative (high-confidence edges only), weighted, and pessimistic (all edges) counts along with a confidence profile.
Usage
vokt blast <function-id> [--depth <n>] [--threshold <confidence>]
Flags
| Flag | Description |
|---|---|
| <function-id> | The function to analyze (e.g., "pkg/payment.ProcessPayment") |
| --depth <n> | Maximum BFS depth for blast computation (default: unlimited) |
| --threshold <confidence> | Minimum edge confidence to include in conservative count (default: 0.30). Use 0.0 to include all edges. |
Examples
# Show blast radius for a function vokt blast "pkg/payment.ProcessPayment" # Limit to 3 levels of callers vokt blast "pkg/payment.ProcessPayment" --depth 3 # Include all edges regardless of confidence vokt blast "pkg/payment.ProcessPayment" --threshold 0.0
Example Output
Function: PaymentService.processPayment Blast radius (conservative, conf >= 0.85): 23 Blast radius (weighted): 31.4 Blast radius (upper bound, all edges): 47 Max depth: 4 Edge confidence profile: High confidence (>=0.85): 68% of edges in blast zone Medium (0.50-0.85): 21% of edges Low (<0.50, mostly DI/CHA): 11% of edges Modules reached: pkg/payment, pkg/order, pkg/billing, pkg/api Reliability: HIGH — most blast zone edges are well-resolved
vokt serve
Launch the web viewer
Starts a local web server for interactive exploration of call graphs, metrics, risk profiles, and behavioral diffs. Reads from the local analysis store.
Usage
vokt serve [--port <n>]
Flags
| Flag | Description |
|---|---|
| --port <n> | Port to serve on (default: 8080) |
Examples
# Start the web viewer vokt serve # Start on a specific port vokt serve --port 3000
vokt verify-graph
Verify analysis quality
Diagnostic command that samples functions from the analysis results and reports resolution rate, confidence distribution, and CHA fallback nodes. Run this first when analyzing a new codebase to understand how reliable the metrics will be.
Usage
vokt verify-graph [--sample <n>]
Flags
| Flag | Description |
|---|---|
| --sample <n> | Number of random functions to sample (default: 100) |
Examples
# Verify graph quality with default sample size vokt verify-graph # Sample 500 functions for a more thorough check vokt verify-graph --sample 500
Example Output
Analysis Quality Report
Total nodes: 2,847
Total edges: 11,234
Resolution rate: 87.3%
Edge confidence distribution:
High (>= 0.85): 72.1%
Medium (0.50-0.85): 18.4%
Low (< 0.50): 9.5%
CHA fallback edges: 312 (2.8%)
DI synthetic edges: 187 (1.7%)
Recommendation: GOOD — resolution rate above 85%.
Metrics are reliable for this codebase.