Command Reference

Eva provides a suite of natural language and deterministic local commands. Below is the comprehensive command reference.

AI Intelligence Commands

`eva ask`

Ask a one-shot question to the LLM, optionally passing local files or directories as context.


# Basic question
eva ask "Explain the difference between a process and a thread"
 
# Include file context
eva ask "What does this module do?" --file src/eva/cli.py
 
# Include multiple file contexts
eva ask "Compare these modules" --file src/eva/cli.py --file src/eva/config.py
 
# Include directory context (respects .gitignore)
eva ask "Where should I add a new provider?" --dir src/eva
 
# Pack entire repository context up to provider budget (with dry-run summary)
eva ask "Explain codebase architecture" --repo . --dry-run
 
# Pack entire repository context and skip confirmation prompt
eva ask "Find architectural flaws" --repo . --yes
 
# Bypass response cache
eva ask "Why did this fail?" --no-cache
 
# Structured JSON output for scripting and CI
eva ask "List open issues" --format json
 
# Bypass .eva/context.md project memory
eva ask "What is the entry point?" --no-project-context

`eva investigate`

Agentic, multi-turn, query-driven repository exploration (Codex/Claude Code-style). The LLM receives the question first and actively calls read-only tools (list_directory, read_file, search_code) to inspect relevant files before delivering a final answer.


# Agentic repo investigation
eva investigate "Find how CLI commands are registered and explain the app flow" . --yes
 
# Custom turn cap and provider
eva investigate "Trace where budget limits are checked" . --max-turns 10 --provider groq --yes
 
# Force include specific denylisted files (audited)
eva investigate "Analyze security certificates" . --force-include server.pem --yes

Comparison: `eva investigate` vs `eva ask --repo`

Feature	`eva ask --repo`	`eva investigate`
Execution Model	Single-pass context dump	Multi-turn iterative tool calling
Context Selection	Query-blind (dependency centrality, file size)	Query-driven (model decides what to read)
Tool Calling	None	`list_directory`, `read_file`, `search_code`
Token Usage	Pre-packs files up to token budget	Reads only files needed for the query
Supported Providers	All providers	Tool-capable providers (`groq`, `openrouter`, `opencode_zen`, `gemini`)
Sensitive Overrides	Supported (`--force-include`)	Supported (`--force-include`)

`eva explain`

Explain a file, concept, or repository with automatic stack detection and module dependency graph extraction.


eva explain src/eva/router
 
# Structured JSON output
eva explain src/eva/security --format json

`eva analyze`

Analyze piped terminal output from stdin. Useful for diagnostic analysis of test failures or build logs.


pytest -q | eva analyze "Summarize the test failures and root cause"

`eva chat`

Run an interactive session chat with persistent memory and session state.


# Start or attach to a named chat session
eva chat --session refactor-router
 
# Resume a previous session
eva chat --session refactor-router --resume

`eva work`

Generate and optionally execute a single safe local command from natural language input.


# Dry run command generation with safety scan
eva work "list the largest files in this repository" --dry-run
 
# Full safety check transparency report
eva work "find all TODO comments" --dry-run-explain
 
# Re-enable shell feature evaluation (pipes / redirects)
eva work "find top memory using processes" --allow-shell-features
 
# Bypass repository .eva/context.md project memory
eva work "format codebase" --no-project-context

`eva edit`

Generate a reviewable unified diff patch for one or more files based on desired modifications.


# Generate patch
eva edit "add validation for empty provider names" --file src/eva/cli.py
 
# Apply generated patch directly after confirmation
eva edit "add validation for empty provider names" --file src/eva/cli.py --apply

Project Memory Commands

`eva context show`

Display project memory loaded from .eva/context.md at the repository root.


eva context show

Note: .eva/context.md is automatically loaded into prompt context for eva ask and eva work to provide project-specific conventions without needing manual --file flags.

Workflow & Workspace Management

`eva workflow`

Declarative multi-step YAML workflow execution with human approval gates.

Subcommand	Description
`eva workflow run <name>`	Execute a declarative multi-step workflow step-by-step.
`eva workflow run <name> -y`	Auto-approve all steps (useful for piping / CI).
`eva workflow list`	List available built-in and custom user workflows.
`eva workflow show <name>`	Display workflow steps and commands without running them.

`eva workspace`

Manage isolated session workspaces, notes, bookmarks, and activity tracking.


eva workspace create feature-auth   # Create isolated workspace
eva workspace switch feature-auth   # Switch active workspace
eva workspace list                 # List all session workspaces
eva workspace note "Check JWT key" # Add note (auto-redacts secrets)
eva workspace bookmark src/auth.py # Bookmark file or URL
eva workspace show                 # Show workspace history & notes

`eva replay`

Replay recorded terminal execution sessions with step controls.


eva replay --list
eva replay session-2026-08-10

Security Assessment Commands

`eva sec`

Run authorized repository security assessment, defensive media forensics, report normalization, scoped ZAP baseline testing, and declarative security workflows.

Subcommand	Description
`eva sec doctor`	Detect optional tools, versions, supported features, and install guidance.
`eva sec assess [PATH]`	Run Trivy, Semgrep, Gitleaks, and optional OSV/Syft local assessment adapters.
`eva sec media <CMD> <FILE>`	Run Aegis forensic media analysis, steganography, signing, and file utilities.
`eva sec ingest <REPORT>`	Import SARIF, scanner JSON, or Aegis JSON into Eva’s finding schema.
`eva sec report [REPORT]`	Produce terminal, JSON, Markdown, and SARIF reports.
`eva sec run <PLAN.yaml>`	Execute a Pydantic-validated declarative security workflow.
`eva sec zap <URL> --scope <scope.yaml>`	Run an authorized passive ZAP baseline scan.


eva sec assess . --format terminal --format sarif
eva sec media analyze ./evidence/photo.jpg
eva sec media sign ./evidence/photo.jpg --key secretkey
eva sec run ./examples/sec/local-repo-assessment.yaml --dry-run
eva sec zap https://staging.example.internal --scope ./examples/sec/scope.yaml --dry-run

ZAP active scanning requires --active, a non-expired scope file with allow_active_scanning: true, and confirmation unless --yes is supplied. --yes never bypasses invalid scope.

See Eva Sec for full Aegis media operations, workflow schema, scope-file rules, and SARIF integration.

Git Intelligence Commands

`eva changes`

Explain unstaged or staged git diff changes.


eva changes
eva changes --staged

`eva commit-message`

Generate a concise, conventional git commit message from staged changes.


git add .
eva commit-message

Authorized Security Operations (`eva sec`)

Eva Sec provides deterministic defensive security analysis, malware inspection, and threat intelligence.

Command	Purpose
`eva sec yara scan <path>`	Scan files/directories using curated defensive YARA rules.
`eva sec yara compile <dir>`	Compile raw `.yar` rules into high-performance binary rules.
`eva sec binary elf <file>`	Audit ELF mitigations (Stack Canary, RELRO, PIE, NX) and W^X violations.
`eva sec binary pe <file>`	Audit PE headers, ASLR, DEP/NX, and RWX section violations.
`eva sec binary entropy <file>`	Compute Shannon entropy to detect packed/encrypted blocks.
`eva sec binary strings <file>`	Extract ASCII/UTF-16 strings with automatic IOC classification.
`eva sec intel cve <cve-id>`	Live vulnerability enrichment via NIST NVD API v2.
`eva sec intel ioc <ioc>`	Threat feed enrichment with RFC 1918 internal IP leak protection.
`eva sec intel extract <target>`	Parse logs/text for IOCs with false-positive filtering.
`eva sec ingest <report>`	Normalize scanner and endpoint triage JSON reports.
`eva sec report`	Render Markdown, SARIF 2.1.0, JSON, or Terminal finding reports.
`eva sec doctor`	Check installed security tooling status.
`eva sec media`	Defensive media forensics through embedded Aegis engine.


# Scan directory with YARA rules and output SARIF
eva sec yara scan /var/www/html --recursive --format sarif
 
# Audit binary exploit mitigations
eva sec binary elf /usr/bin/daemon
eva sec binary pe payload.exe
 
# Shannon entropy analysis
eva sec binary entropy sample.bin --block-size 1024
 
# Live CVE query from NIST NVD
eva sec intel cve CVE-2021-44228
 
# Enrich IOC while protecting internal RFC 1918 addresses
eva sec intel ioc 198.51.100.45
 
# Ingest and normalize endpoint triage report
eva sec ingest /tmp/audit_hardening.json --format markdown --format sarif

Deterministic Local Commands (Zero Quota)

These utility commands run 100% locally and consume no LLM provider quota.

Command	Purpose
`eva find "<pattern>"`	Fast local file matching.
`eva tree [dir]`	Print a `.gitignore`-aware directory tree.
`eva usage`	View local provider RPM and RPD usage counters.
`eva cache clear`	Clear cached LLM response objects.

Configuration Commands


eva config set-key <provider>                  # Store key in OS keyring
eva config remove-key <provider>               # Remove key from OS keyring
eva config set-model <provider> <model>        # Configure default model for provider
eva config doctor                              # Run diagnostic health check on environment
eva config allow-command <prefix>              # Add command prefix to execution allowlist
eva config disallow-command <prefix>           # Remove command prefix from execution allowlist
eva config import-allowlist <path>             # Import allowlist from a file
eva config set-redaction-threshold <val>       # Set Shannon entropy threshold (default 3.5)
eva config allow-redaction-pattern <regex>     # Add regex pattern to secret redaction ignore list
eva config disallow-redaction-pattern <regex>  # Remove pattern from secret redaction ignore list
eva config ignore-dir <name>                   # Add directory to process-wide ignored dirs
eva config unignore-dir <name>                 # Remove directory from process-wide ignored dirs
eva config allow-sensitive-file <glob>         # Add glob pattern to sensitive file allowlist
eva config disallow-sensitive-file <glob>      # Remove glob pattern from sensitive file allowlist

Scripting & Automation Options

Eva commands accept global and command-specific automation flags:

--format json|text: Supported on eva ask and eva explain to output deterministic machine-readable JSON:


{
  "content": "Explanation or answer text...",
  "is_error": false,
  "provider": "groq",
  "model": "llama-3.3-70b-versatile"
}

--no-project-context: Skip auto-injecting repository-level .eva/context.md project memory.
--force-include <pattern>: Authorize reading specific denylisted sensitive files (*.pem, .env, etc.) in eva investigate and eva ask --repo.

Shell & Global Options


eva --version                               # Print Eva version
eva --verbose ask "Why did this fail?"      # Enable verbose diagnostics logging
eva --install-completion                    # Install shell completion (bash/zsh/fish)
eva --show-completion                       # Print shell completion script

Command Reference

AI Intelligence Commands

eva ask

eva investigate

Comparison: eva investigate vs eva ask --repo

eva explain

eva analyze

eva chat

eva work

eva edit