Uploading README.md…

Eva CLI

Eva is a command line intelligence assistant. It uses deterministic local tools for file discovery, tree generation, search, configuration, caching, and quota tracking, while reserving LLM calls for natural-language reasoning, summarization, code review, command generation, and patch generation.

The design goal is practical: keep routine terminal work fast and local, "Can't remember the right command... Don't leave CLI just for a single command and simple work insted ask eva directly from your CLI"

Quick Demo

"Forgot a command?". Ask eva

"Need help understanding any command output?". Ask eva

"Want to patch a script?". Ask eva

"Need a chatbot?". Just eva

Highlights

• Provider abstraction with fallback routing across OpenRouter, Groq, Gemini, and OpenCode Zen.
• Streaming responses with disk-backed caching.
• Local RPM/RPD budget tracking to avoid unexpectedly exhausting free-tier provider quotas.
• .gitignore-aware context collection with common heavy directories pruned automatically.
• Safe file-context reads with missing-file, binary-file, large-file, and invalid-UTF-8 handling.
• Hardened command generation via eva work: strict parsing, risk checks, no shell=True, dry-run mode, and audit logging.
• Git-aware workflows for explaining diffs and generating commit messages.
• Reviewable patch generation with eva edit.
• Health checks through eva config doctor.
• Persistent chat sessions with eva chat --session.

Installation

Eva requires Python 3.10 or newer.

Quick install:

curl -fsSL https://raw.githubusercontent.com/rootagi/eva/main/install.sh | sh

Or with a package manager, once published to PyPI:

uv tool install eva-cli    # or: pipx install eva-cli / pip install --user eva-cli

Or with Docker (no Python required):

docker run --rm -it -v "$(pwd):/workspace" -e EVA_OPENAI_API_KEY="$OPENAI_API_KEY" \
  ghcr.io/rootagi/eva chat

From a local checkout (for contributing):

python -m pip install -e .

For development:

python -m pip install -e ".[dev]"

Configuration

Set the default provider:

eva use groq

Store an API key using the OS keyring:

eva config set-key groq

Headless environments such as containers, CI runners, and SSH-only servers may not have a usable OS keyring backend. In that case, use provider-specific environment variables:

export EVA_GROQ_API_KEY="..."
export EVA_OPENROUTER_API_KEY="..."
export EVA_GEMINI_API_KEY="..."
export EVA_OPENCODE_ZEN_API_KEY="..."

Check the local setup:

eva config doctor

Usage

Ask a one-shot question:

eva ask "Explain the difference between a process and a thread"

Include a file as context:

eva ask "What does this module do?" --file src/eva/cli.py

Include a directory tree as context:

eva ask "Where should I add a new provider?" --dir src/eva

Explain a file or directory:

eva explain src/eva/router

Analyze piped output:

pytest -q | eva analyse "Summarize the failures"

Start an interactive chat session:

eva chat --session refactor-router
eva chat --session refactor-router --resume

Generate a safe command from natural language:

eva work "list the largest files in this repository" --dry-run

Explain current git changes:

eva changes
eva changes --staged

Generate a commit message:

eva commit-message

Generate a reviewable patch:

eva edit "add validation for empty provider names" --file src/eva/cli.py

Apply the generated patch after confirmation:

eva edit "add validation for empty provider names" --file src/eva/cli.py --apply

Local utility commands do not use LLM quota:

eva find "*.py"
eva tree src/eva

Command reference

Command	Purpose
eva ask	Ask a one-shot question, optionally with file or directory context.
eva explain	Explain a file, concept, or repository (with stack detection & module dependency graph).
eva analyse / eva analyze	Analyze piped terminal output.
eva chat	Run an interactive chat session, optionally saved and resumed.
eva work	Generate and optionally execute a single safe local command.
eva edit	Generate a unified diff for one or more files.
eva workflow run	Walk through a declarative multi-step YAML workflow with human approval gates.
eva workflow list	List available built-in and user-defined workflows.
eva workflow show	Display workflow steps and commands without executing them.
eva workspace	Manage isolated session workspaces, notes, and bookmarks.
eva workspace create	Create a new named session workspace.
eva workspace switch	Switch to a named session workspace.
eva workspace list	List all session workspaces.
eva workspace note	Add a note to the active workspace (secrets redacted automatically).
eva workspace bookmark	Bookmark a file path or URL in the active workspace.
eva workspace show	Display notes, bookmarks, and activity history for a workspace.
eva replay	Replay recorded terminal execution sessions (eva replay <session> or eva replay --list).
eva changes	Explain unstaged or staged git changes.
eva commit-message	Generate a concise commit message from a git diff.
eva find	Find files locally without AI usage.
eva tree	Print a .gitignore-aware directory tree.
eva usage	Show normalized local provider usage counters.

| eva config set-key <provider> | Store an API key in the OS keyring. | | eva config remove-key <provider> | Delete a stored API key from the OS keyring. | | eva config set-model <provider> <model> | Set active model for a provider. | | eva config | Manage provider, model, and API-key configuration. | | eva cache clear | Clear cached AI responses. |

Global options:

eva --version
eva --verbose ask "Why did this fail?"

Verbose mode writes diagnostics to stderr and to Eva’s log file.

Safety model & Production Hardening

eva work and eva workflow are intentionally conservative:

• model output must resolve to exactly one command line;
• malformed Markdown fences and trailing explanations are rejected;
• shell operators such as pipes, redirects, command substitution, and chained commands are rejected;
• high-risk patterns such as sudo, rm -rf, curl | bash, dd, mkfs, recursive ownership changes, and system-path redirects are blocked;
• secrets, API keys, tokens, and high-entropy strings are redacted before any network request and before writing to local disk;
• every generated, blocked, declined, or executed command is recorded in a cryptographic hash-chained audit log with SHA-256 tamper verification;
• optional sandboxed execution (sandbox_risky_commands = true in config) runs commands in a stripped subprocess environment with environment variable isolation and strict timeouts.

See SECURITY.md for full security documentation.

Opt-in Telemetry

Eva collects zero data by default (telemetry_enabled = false). When explicitly opted-in via configuration, Eva records only anonymized provider response latency, error types, and success status. Prompt text, code snippets, file contents, and terminal commands are never collected. An optional self-hosted export endpoint is supported via telemetry_export_endpoint.

Provider behavior

Eva tries the configured default provider first. If fallback is enabled, it then tries providers in the configured fallback order. Provider failures are logged instead of being silently discarded, and final provider failure messages include a concise summary of what failed.

Configured providers:

• OpenRouter
• Groq
• Gemini
• OpenCode Zen
• Ollama (offline local backend)
• llama.cpp (offline GGUF backend)

Development

Install development dependencies:

python -m pip install -e ".[dev]"

Run tests:

pytest

Run linting:

ruff check .

Run the same checks in CI by pushing to a branch or opening a pull request. See .github/workflows/ci.yml.

Project files

• pyproject.toml — package metadata, dependencies, and tooling.
• CHANGELOG.md — release history.
• LICENSE — MIT license.
• src/eva — CLI implementation.
• tests — regression tests.

License

Eva CLI is released under the MIT License.