Reference

CLI Reference

Complete command-line reference for semfora-engine.

Quick Reference

# Analyze a file or directory
semfora-engine analyze src/main.rs
semfora-engine analyze ./src --output-mode symbols_only

# Search for code (hybrid: symbol + semantic by default)
semfora-engine search "authenticate" --limit 10
semfora-engine search --symbols "login" --kind fn

# Generate semantic index with smart refresh
semfora-engine index generate
semfora-engine index generate --force --incremental

# Get repository overview
semfora-engine query overview --max-modules 50

# Analyze git changes
semfora-engine analyze --diff main --limit 20
semfora-engine analyze --uncommitted --summary-only

# Find callers with depth control
semfora-engine query callers <hash> --depth 2 --limit 30

# Quality validation with duplicate detection
semfora-engine validate --module api --duplicates
semfora-engine validate --file-path src/auth.rs --include-source

# Lint with auto-detection and fixes
semfora-engine lint scan --fixable-only
semfora-engine lint fix --dry-run --safe-only

# Trace dependencies
semfora-engine trace <symbol> --direction both --depth 3

Main Commands

Top-level commands available in the semfora-engine CLI.

Command	Alias	Description
`analyze`	`a`	Analyze files, directories, or git changes with 19 parameters including diff analysis
`search`	`s`	Unified search with symbol/semantic/raw modes and 15 parameters
`query`	`q`	Query the semantic index with 7 subcommands (overview, module, symbol, source, callers, callgraph, file, languages)
`trace`	-	Dependency tracing with direction controls and depth parameters
`validate`	`v`	Quality validation with duplicate detection and complexity analysis
`index`	-	Semantic index management with generate, check, and export subcommands
`cache`	-	Cache management with info, clear, and prune subcommands
`test`	-	Test framework detection and execution
`lint`	`l`	Code linting with scan, fix, typecheck, detect, and recommend modes
`commit`	-	Git commit analysis and preparation with semantic metrics
`setup`	-	MCP client setup with agent installation options
`uninstall`	-	Remove MCP/engine components with selective cleanup
`config`	-	Configuration management with show, set, and reset options
`benchmark`	-	Performance testing and token efficiency measurement
`serve`	-	Start repository server with file watching and git polling

Query Subcommands

Query the semantic index for symbols, source code, and call relationships

Usage: semfora-engine query <subcommand>

Subcommand	Description
`overview`	Get repository overview with modules and risk breakdown
`module`	Get a specific module's symbols and details
`symbol`	Get symbol information by hash or file location
`source`	Get source code for files or symbols with context
`callers`	Get callers of a symbol with depth control (max 3)
`callgraph`	Get call graph with module/symbol filtering and SQLite export
`file`	Get all symbols in a file with risk and kind filtering
`languages`	List all supported programming languages

Index Subcommands

Manage the semantic index for your repository

Usage: semfora-engine index <subcommand>

Subcommand	Description
`generate`	Generate or refresh semantic index with incremental options
`check`	Check index freshness and auto-refresh capabilities
`export`	Export the complete index to SQLite database

Cache Subcommands

Manage the local cache system

Usage: semfora-engine cache <subcommand>

Subcommand	Description
`info`	Show comprehensive cache information and statistics
`clear`	Clear cache for the current directory
`prune`	Remove caches older than specified days

Lint Subcommands

Code linting with auto-detection of 26+ linters across 16 languages

Usage: semfora-engine lint <subcommand>

Subcommand	Description
`scan`	Scan for linting issues (default mode)
`fix`	Auto-fix linting issues with dry-run and safety options
`typecheck`	Run type checking only
`detect`	Detect available linters for the project
`recommend`	Recommend linters for the project setup

Config Subcommands

Manage semfora configuration settings

Usage: semfora-engine config <subcommand>

Subcommand	Description
`show`	Display current configuration values
`set`	Set configuration key-value pairs
`reset`	Reset configuration to default values

Global Options

These options can be used with any command.

Option	Description
`-f, --format <FORMAT>`	Output format: text (default), toon, json
`-v, --verbose`	Show verbose output
`--progress`	Show progress percentage during long operations

Exit Codes

Code	Meaning
`0`	Success
`1`	File not found or IO error
`2`	Unsupported language
`3`	Parse failure
`4`	Semantic extraction or query error
`5`	Git error (not a git repo, etc.)

Environment Variables

RUST_LOG

Control logging verbosity

RUST_LOG=semfora_engine=debug semfora-engine analyze ./src

Example Workflows

Initial Setup & Analysis

# 1. Generate index for a project (smart refresh)
cd my-project
semfora-engine index generate

# 2. Get project overview with modules
semfora-engine query overview --max-modules 50

# 3. Search with different modes
semfora-engine search "authenticate" --kind fn --limit 20
semfora-engine search --symbols "Config" --module api
semfora-engine search --raw "TODO|FIXME" --file-types rs,ts

# 4. Get symbol details and source
semfora-engine query symbol --hash <hash> --source --context 5
semfora-engine query source --file src/main.rs --start 10 --end 50

Code Review Workflow

# Analyze PR changes with semantic analysis
semfora-engine analyze --diff main --limit 50 --offset 0

# Analyze uncommitted changes before commit  
semfora-engine analyze --uncommitted --target-ref WORKING

# Get summary for large diffs first
semfora-engine analyze --diff main --summary-only

# Prepare detailed commit information
semfora-engine commit --metrics --all-metrics

# Review specific files with symbols
semfora-engine query file src/auth.rs --source --context 3

Quality & Validation

# Comprehensive quality validation
semfora-engine validate --module api --include-source
semfora-engine validate --duplicates --threshold 0.85 --sort-by similarity

# Lint with multiple modes
semfora-engine lint scan --fixable-only --limit 100
semfora-engine lint fix --safe-only --dry-run
semfora-engine lint typecheck --limit 50

# Trace dependencies and impact analysis
semfora-engine trace <symbol_name> --direction both --depth 2
semfora-engine query callers <hash> --depth 3 --source

Performance & Setup

# Benchmark token efficiency
semfora-engine benchmark ./large-project

# Setup MCP integration with agents
semfora-engine setup --clients cursor,vscode --with-agents
semfora-engine setup --list-clients --agents-scope project

# Server mode for AI integration
semfora-engine serve --repo . --no-git-poll

# Cache management
semfora-engine cache info
semfora-engine cache prune 30  # older than 30 days