eva-cli 4.0.0__tar.gz → 4.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (178) hide show
  1. {eva_cli-4.0.0 → eva_cli-4.1.0}/.github/workflows/fastwalk-release.yml +26 -2
  2. {eva_cli-4.0.0 → eva_cli-4.1.0}/CHANGELOG.md +61 -0
  3. {eva_cli-4.0.0 → eva_cli-4.1.0}/PKG-INFO +34 -5
  4. {eva_cli-4.0.0 → eva_cli-4.1.0}/README.md +32 -3
  5. eva_cli-4.1.0/docs/README.md +19 -0
  6. eva_cli-4.1.0/docs/architecture.md +94 -0
  7. eva_cli-4.1.0/docs/command-reference.md +197 -0
  8. eva_cli-4.1.0/docs/configuration.md +140 -0
  9. eva_cli-4.1.0/docs/index.md +83 -0
  10. eva_cli-4.1.0/docs/plugins.md +92 -0
  11. eva_cli-4.1.0/docs/provider-behavior.md +60 -0
  12. eva_cli-4.1.0/docs/security-model.md +117 -0
  13. {eva_cli-4.0.0 → eva_cli-4.1.0}/pyproject.toml +1 -1
  14. {eva_cli-4.0.0 → eva_cli-4.1.0}/rust/eva_fastwalk/Cargo.toml +1 -1
  15. {eva_cli-4.0.0 → eva_cli-4.1.0}/rust/eva_fastwalk/src/lib.rs +5 -3
  16. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/__init__.py +1 -1
  17. eva_cli-4.1.0/src/eva/agent/__init__.py +12 -0
  18. eva_cli-4.1.0/src/eva/agent/loop.py +251 -0
  19. eva_cli-4.1.0/src/eva/agent/tools.py +174 -0
  20. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/cli/app.py +215 -4
  21. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/config/config.py +1 -0
  22. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/indexing/__init__.py +3 -0
  23. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/indexing/io.py +1 -2
  24. eva_cli-4.1.0/src/eva/indexing/packer.py +237 -0
  25. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/indexing/repo_index.py +1 -1
  26. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/indexing/tokenizer.py +2 -2
  27. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/prompts/__init__.py +5 -0
  28. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/providers/__init__.py +111 -0
  29. eva_cli-4.1.0/src/eva/providers/gemini_provider.py +156 -0
  30. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/providers/llamacpp_provider.py +4 -2
  31. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/providers/ollama_provider.py +4 -2
  32. eva_cli-4.1.0/src/eva/providers/openai_compat.py +146 -0
  33. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/security/__init__.py +3 -0
  34. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/security/audit.py +21 -1
  35. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/security/redaction.py +3 -3
  36. eva_cli-4.1.0/src/eva/security/sensitive_files.py +31 -0
  37. eva_cli-4.1.0/src/eva/shell/runner.py +11 -0
  38. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/telemetry/diagnostics.py +4 -2
  39. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/workspace/git_ops.py +14 -3
  40. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/workspace/gitignore.py +0 -1
  41. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/conftest.py +6 -0
  42. eva_cli-4.1.0/tests/fixtures/golden/prompts/changes_system_prompt.txt +3 -0
  43. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/test_basic.py +4 -4
  44. eva_cli-4.1.0/tests/unit/agent/test_loop.py +116 -0
  45. eva_cli-4.1.0/tests/unit/agent/test_tools.py +53 -0
  46. eva_cli-4.1.0/tests/unit/cli/test_ask_repo.py +97 -0
  47. eva_cli-4.1.0/tests/unit/cli/test_changes_command.py +51 -0
  48. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/cli/test_cli_commands.py +56 -1
  49. eva_cli-4.1.0/tests/unit/cli/test_investigate.py +68 -0
  50. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/golden/test_golden_prompts.py +7 -0
  51. eva_cli-4.1.0/tests/unit/indexing/test_packer.py +72 -0
  52. eva_cli-4.1.0/tests/unit/providers/test_context_budget.py +26 -0
  53. eva_cli-4.1.0/tests/unit/providers/test_dispatch_caching.py +102 -0
  54. eva_cli-4.1.0/tests/unit/providers/test_gemini_tools.py +58 -0
  55. eva_cli-4.1.0/tests/unit/providers/test_openai_compat_tools.py +72 -0
  56. eva_cli-4.1.0/tests/unit/providers/test_provider_tools_protocol.py +42 -0
  57. eva_cli-4.1.0/tests/unit/providers/test_repo_caching.py +33 -0
  58. eva_cli-4.1.0/tests/unit/security/test_audit.py +29 -0
  59. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/telemetry/test_telemetry.py +3 -0
  60. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/test_compatibility_imports.py +16 -0
  61. eva_cli-4.0.0/src/eva/budget.py +0 -31
  62. eva_cli-4.0.0/src/eva/cache.py +0 -19
  63. eva_cli-4.0.0/src/eva/chat_session.py +0 -5
  64. eva_cli-4.0.0/src/eva/config.py +0 -35
  65. eva_cli-4.0.0/src/eva/diagnostics.py +0 -9
  66. eva_cli-4.0.0/src/eva/git_ops.py +0 -15
  67. eva_cli-4.0.0/src/eva/providers/gemini_provider.py +0 -72
  68. eva_cli-4.0.0/src/eva/providers/openai_compat.py +0 -57
  69. eva_cli-4.0.0/src/eva/shell/runner.py +0 -6
  70. eva_cli-4.0.0/src/eva/work_safety.py +0 -21
  71. {eva_cli-4.0.0 → eva_cli-4.1.0}/.github/workflows/ci.yaml +0 -0
  72. {eva_cli-4.0.0 → eva_cli-4.1.0}/.github/workflows/release.yml +0 -0
  73. {eva_cli-4.0.0 → eva_cli-4.1.0}/.gitignore +0 -0
  74. {eva_cli-4.0.0 → eva_cli-4.1.0}/.pre-commit-config.yaml +0 -0
  75. {eva_cli-4.0.0 → eva_cli-4.1.0}/CONTRIBUTING.md +0 -0
  76. {eva_cli-4.0.0 → eva_cli-4.1.0}/Dockerfile +0 -0
  77. {eva_cli-4.0.0 → eva_cli-4.1.0}/LICENSE +0 -0
  78. {eva_cli-4.0.0 → eva_cli-4.1.0}/SECURITY.md +0 -0
  79. {eva_cli-4.0.0 → eva_cli-4.1.0}/assets/demo.gif +0 -0
  80. {eva_cli-4.0.0 → eva_cli-4.1.0}/assets/demo2.gif +0 -0
  81. {eva_cli-4.0.0 → eva_cli-4.1.0}/assets/demo3.gif +0 -0
  82. {eva_cli-4.0.0 → eva_cli-4.1.0}/assets/demo4.gif +0 -0
  83. {eva_cli-4.0.0 → eva_cli-4.1.0}/assets/demo5.gif +0 -0
  84. {eva_cli-4.0.0 → eva_cli-4.1.0}/assets/eva.png +0 -0
  85. {eva_cli-4.0.0 → eva_cli-4.1.0}/examples/eva-plugin-hello/README.md +0 -0
  86. {eva_cli-4.0.0 → eva_cli-4.1.0}/examples/eva-plugin-hello/eva_plugin_hello.py +0 -0
  87. {eva_cli-4.0.0 → eva_cli-4.1.0}/examples/eva-plugin-hello/pyproject.toml +0 -0
  88. {eva_cli-4.0.0 → eva_cli-4.1.0}/install.sh +0 -0
  89. {eva_cli-4.0.0 → eva_cli-4.1.0}/rust/eva_fastwalk/Cargo.lock +0 -0
  90. {eva_cli-4.0.0 → eva_cli-4.1.0}/rust/eva_fastwalk/pyproject.toml +0 -0
  91. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/cache/__init__.py +0 -0
  92. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/cache/cache.py +0 -0
  93. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/cli/__init__.py +0 -0
  94. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/cli.py +0 -0
  95. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/config/__init__.py +0 -0
  96. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/indexing/finder.py +0 -0
  97. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/indexing/tree.py +0 -0
  98. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/plugins/__init__.py +0 -0
  99. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/plugins/loader.py +0 -0
  100. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/plugins/protocol.py +0 -0
  101. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/providers/groq_provider.py +0 -0
  102. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/providers/opencode_zen_provider.py +0 -0
  103. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/providers/openrouter_provider.py +0 -0
  104. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/replay/__init__.py +0 -0
  105. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/replay/player.py +0 -0
  106. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/replay/recorder.py +0 -0
  107. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/security/sandbox.py +0 -0
  108. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/security/work_safety.py +0 -0
  109. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/shell/__init__.py +0 -0
  110. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/telemetry/__init__.py +0 -0
  111. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/telemetry/metrics.py +0 -0
  112. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/ui/formatter.py +0 -0
  113. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/ui/streaming.py +0 -0
  114. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/workflows/__init__.py +0 -0
  115. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/workflows/budget.py +0 -0
  116. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/workflows/builtins/dependency_audit.yaml +0 -0
  117. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/workflows/builtins/repo_health.yaml +0 -0
  118. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/workflows/builtins/security_scan.yaml +0 -0
  119. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/workflows/chat_session.py +0 -0
  120. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/workflows/engine.py +0 -0
  121. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/workspace/__init__.py +0 -0
  122. {eva_cli-4.0.0 → eva_cli-4.1.0}/src/eva/workspace/session.py +0 -0
  123. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/fixtures/golden/patches/sample1_expected.diff +0 -0
  124. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/fixtures/golden/patches/sample1_fenced.txt +0 -0
  125. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/fixtures/golden/prompts/analyze_system_prompt.txt +0 -0
  126. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/fixtures/golden/prompts/ask_system_prompt.txt +0 -0
  127. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/fixtures/golden/prompts/chat_system_prompt.txt +0 -0
  128. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/fixtures/golden/prompts/commit_system_prompt.txt +0 -0
  129. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/fixtures/golden/prompts/edit_system_prompt.txt +0 -0
  130. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/fixtures/golden/prompts/explain_system_prompt.txt +0 -0
  131. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/fixtures/golden/prompts/work_system_prompt.txt +0 -0
  132. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/__init__.py +0 -0
  133. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/cache/__init__.py +0 -0
  134. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/cache/test_cache.py +0 -0
  135. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/cli/__init__.py +0 -0
  136. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/cli/test_cli.py +0 -0
  137. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/cli/test_cli_coverage.py +0 -0
  138. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/cli/test_cli_more.py +0 -0
  139. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/config/__init__.py +0 -0
  140. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/config/test_config.py +0 -0
  141. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/config/test_config_keys.py +0 -0
  142. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/golden/__init__.py +0 -0
  143. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/golden/test_golden_patches.py +0 -0
  144. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/indexing/__init__.py +0 -0
  145. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/indexing/test_indexing.py +0 -0
  146. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/indexing/test_indexing_more.py +0 -0
  147. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/indexing/test_repo_index.py +0 -0
  148. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/indexing/test_tokenizer_offline.py +0 -0
  149. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/plugins/__init__.py +0 -0
  150. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/plugins/test_plugins.py +0 -0
  151. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/providers/__init__.py +0 -0
  152. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/providers/test_offline_providers.py +0 -0
  153. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/providers/test_provider_coverage.py +0 -0
  154. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/providers/test_provider_errors.py +0 -0
  155. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/providers/test_providers.py +0 -0
  156. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/providers/test_providers_more.py +0 -0
  157. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/replay/test_replay.py +0 -0
  158. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/security/__init__.py +0 -0
  159. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/security/test_allowlist_cli.py +0 -0
  160. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/security/test_audit_chain.py +0 -0
  161. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/security/test_redaction.py +0 -0
  162. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/security/test_safety_audit.py +0 -0
  163. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/security/test_sandbox.py +0 -0
  164. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/security/test_work_safety.py +0 -0
  165. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/shell/__init__.py +0 -0
  166. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/shell/test_shell.py +0 -0
  167. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/telemetry/__init__.py +0 -0
  168. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/telemetry/test_metrics.py +0 -0
  169. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/ui/__init__.py +0 -0
  170. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/ui/test_ui.py +0 -0
  171. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/workflows/__init__.py +0 -0
  172. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/workflows/test_chat_session.py +0 -0
  173. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/workflows/test_workflow_engine.py +0 -0
  174. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/workflows/test_workflows.py +0 -0
  175. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/workspace/__init__.py +0 -0
  176. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/workspace/test_git_ops.py +0 -0
  177. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/workspace/test_session_workspace.py +0 -0
  178. {eva_cli-4.0.0 → eva_cli-4.1.0}/tests/unit/workspace/test_workspace.py +0 -0
@@ -22,6 +22,8 @@ on:
22
22
 
23
23
  permissions:
24
24
  id-token: write # PyPI trusted publishing (OIDC)
25
+ contents: write # to attach files to the GitHub Release
26
+
25
27
 
26
28
  jobs:
27
29
  linux:
@@ -56,10 +58,11 @@ jobs:
56
58
  fail-fast: false
57
59
  matrix:
58
60
  include:
59
- - runner: macos-13 # Intel
61
+ - runner: macos-latest # Intel (cross-compiled)
60
62
  target: x86_64
61
- - runner: macos-14 # Apple Silicon
63
+ - runner: macos-latest # Apple Silicon
62
64
  target: aarch64
65
+
63
66
  steps:
64
67
  - uses: actions/checkout@v4
65
68
  - name: Build wheel
@@ -119,3 +122,24 @@ jobs:
119
122
  - uses: pypa/gh-action-pypi-publish@release/v1
120
123
  with:
121
124
  packages-dir: dist
125
+ skip-existing: true
126
+
127
+
128
+ github-release:
129
+ name: Attach files to GitHub Release
130
+ needs: [linux, macos, windows, sdist]
131
+ runs-on: ubuntu-latest
132
+ permissions:
133
+ contents: write
134
+ steps:
135
+ - uses: actions/download-artifact@v4
136
+ with:
137
+ pattern: wheels-*
138
+ path: dist
139
+ merge-multiple: true
140
+ - name: Create/update GitHub Release
141
+ uses: softprops/action-gh-release@v2
142
+ with:
143
+ files: dist/*
144
+ generate_release_notes: true
145
+
@@ -6,6 +6,67 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
8
 
9
+
10
+ ## [4.1.0] - 2026-08-11
11
+
12
+ ### Added
13
+ - **Agentic Repo Exploration (`eva investigate`):**
14
+ - Added `eva investigate <query> [path]` command for multi-turn, query-driven codebase exploration using tool calling (`list_directory`, `read_file`, `search_code`).
15
+ - Added optional tool-calling capabilities to Provider protocol (`supports_tools`, `TextDelta`/`ToolCall` streaming events, `generate_with_tools`).
16
+ - Implemented streamed tool calling for OpenAI-compatible providers (`groq`, `openrouter`, `opencode_zen`) and `GeminiProvider`.
17
+ - Added upfront provider capability check (`is_tool_capable()`), producing a clear actionable error for non-tool-capable providers (`ollama`, `llamacpp`).
18
+ - Agent loop controller in `src/eva/agent/loop.py` featuring turn limits (`max_turns`), quota accounting per turn (`check_and_increment`), repeated tool call loop detection, and graceful partial answer degradation.
19
+ - Defense-in-depth security: path containment check on every tool call (`Path.resolve()`), sensitive-file denylist (`DENYLIST_PATTERNS`) and `.gitignore` gating, secret redaction (`redact_secrets`), and session-level hash-chained audit logging (`append_investigation_audit`).
20
+ - **Repo-wide context packing (`src/eva/indexing/packer.py`, `src/eva/security/sensitive_files.py`, `src/eva/cli/app.py`):**
21
+ - Added `--repo` flag to `eva ask` to pack entire repositories as plain-text LLM context up to per-provider token budgets.
22
+ - Smart deterministic file ranking prioritizing Python module dependency centrality, shallow directory depth, and file size.
23
+ - Built-in sensitive-file denylist (`DENYLIST_PATTERNS` in `src/eva/security/sensitive_files.py`) excluding `.env`, private keys (`*.pem`, `*.key`), SSH keys (`id_rsa*`, `id_ed25519*`), and credential files independently of `.gitignore` state.
24
+ - User confirmation prompt gating, Rich table summary reports, and `--dry-run` inspection mode.
25
+ - Cryptographic hash-chained audit logging (`action: repo_pack`) for provenance recording of sent repo contexts.
26
+ - **Uniform per-provider context budget lookup (`src/eva/providers/__init__.py`):**
27
+ - Added `get_context_budget(provider_name, config)` returning provider token limits with a conservative default fallback (4000).
28
+
29
+ - **Disk-backed response caching integration (`src/eva/providers/__init__.py`, `src/eva/cli/app.py`):**
30
+ - `dispatch()` now checks and populates the disk cache (backed by `diskcache`) before calling the live provider. Repeated identical requests return instantly from cache.
31
+ - Added `use_cache` parameter to `dispatch()` (default `True`).
32
+ - Added `--no-cache` flag to `eva ask` to bypass the response cache.
33
+ - Error responses (matching `is_ai_error()`) are never written to the cache.
34
+ - **Cache command group (`src/eva/cli/app.py`):**
35
+ - Added `eva cache clear` subcommand to clear all cached responses.
36
+ - **Directory context for ask (`src/eva/cli/app.py`):**
37
+ - Added `--dir` / `-d` option to `eva ask` to include `.gitignore`-aware directory tree context. Supports multiple `--dir` and combined `--dir` + `--file` options with 4000-token budget context trimming.
38
+ - **Git diff explanation command (`src/eva/cli/app.py`, `src/eva/prompts/__init__.py`):**
39
+ - Added `eva changes` command (with `--staged` support) to explain git diffs using dedicated `CHANGES_SYSTEM_PROMPT`.
40
+
41
+ ### Changed
42
+ - **Renamed `eva commit` to `eva commit-message` (`src/eva/cli/app.py`):**
43
+ - Breaking change: renamed CLI command `eva commit` to `eva commit-message` to match documentation. Users scripting against `eva commit` should update their scripts to `eva commit-message`.
44
+ - **Documentation cleanup (`README.md`, `docs/`):**
45
+ - Removed outdated `eva analyse` references across documentation files in favor of `eva analyze`.
46
+
47
+ ### Fixed
48
+ - **`eva-fastwalk` Crate Update (v0.1.1, `rust/eva_fastwalk/`):**
49
+ - Restructured `ALWAYS_IGNORED_DIRS` filtering in `rust/eva_fastwalk/src/lib.rs` so ignore checks apply strictly to directory entries rather than file entries.
50
+ - Bumped version in `rust/eva_fastwalk/Cargo.toml` to `0.1.1`.
51
+ - **Shell Runner Sandboxing (`src/eva/shell/runner.py`):**
52
+ - Updated `execute_shell_command()` to route through `run_sandboxed` with strict environment variable filtering and timeout handling.
53
+ - **Agent Multi-Tool Call Loop Tracking (`src/eva/agent/loop.py`):**
54
+ - Refactored `run_investigation()` signature tracking from single-signature overwrites to turn-level signature list comparison (`last_turn_signatures`), properly identifying multi-tool call loops across turns.
55
+ - **UTF-8 Byte Slicing (`src/eva/indexing/io.py`):**
56
+ - Corrected read limit byte slicing order before UTF-8 decoding to prevent character truncation errors at context limits.
57
+ - **Path Resolution & Fallback Diff Security (`src/eva/workspace/git_ops.py`):**
58
+ - Added target path resolution and containment checks in `apply_diff_python_fallback()`.
59
+ - **Entropy Secret Redaction (`src/eva/security/redaction.py`):**
60
+ - Added URL pattern exclusions (`http://`, `https://`) in high-entropy token detection to avoid false-positive redactions of standard API URLs.
61
+ - **Diagnostics Logging Guard (`src/eva/telemetry/diagnostics.py`):**
62
+ - Replaced function-attribute singleton state with a module-level `_logging_configured` flag for reliable state tracking.
63
+ - **Stack Framework Operator Precedence (`src/eva/indexing/repo_index.py`):**
64
+ - Added explicit parentheses around `conftest.py` and `tests/` directory detection to fix operator evaluation order.
65
+
66
+ ### Removed
67
+ - **Legacy shim cleanup (`src/eva/`):**
68
+ - Removed unused flat compatibility shim files (`config.py`, `cache.py`, `budget.py`, `work_safety.py`, `git_ops.py`, `chat_session.py`, `diagnostics.py`). Code and tests now import directly from standard package locations (`eva.config`, `eva.cache`, `eva.workflows.budget`, `eva.security.work_safety`, `eva.workspace.git_ops`, `eva.workflows.chat_session`, `eva.telemetry.diagnostics`).
69
+
9
70
  ## [4.0.0] - 2026-08-10
10
71
 
11
72
  ### Added
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: eva-cli
3
- Version: 4.0.0
3
+ Version: 4.1.0
4
4
  Summary: Command Line Intelligence
5
5
  License-File: LICENSE
6
6
  Requires-Python: >=3.10
@@ -36,6 +36,7 @@ Description-Content-Type: text/markdown
36
36
 
37
37
  <p align="center">
38
38
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white"></a>
39
+ <a href="https://eva-cli.vercel.app/docs"><img src="https://img.shields.io/badge/Docs-eva--cli.vercel.app%2Fdocs-000000?style=for-the-badge&logo=vercel&logoColor=white"></a>
39
40
  <a href="LICENSE"><img src="https://img.shields.io/github/license/rootagi/eva?style=for-the-badge"></a>
40
41
  <a href="https://github.com/rootagi/eva/actions"><img src="https://img.shields.io/github/actions/workflow/status/rootagi/eva/ci.yaml?style=for-the-badge&label=Build"></a>
41
42
  <a href="#usage"><img src="https://img.shields.io/badge/CLI-Terminal-111827?style=for-the-badge&logo=gnubash&logoColor=white"></a>
@@ -49,6 +50,8 @@ Eva is a command line intelligence assistant. It uses deterministic local tools
49
50
 
50
51
  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"
51
52
 
53
+ 📖 **Website & Documentation**: Full interactive documentation is available at [eva-cli.vercel.app/docs](https://eva-cli.vercel.app/docs) (or offline in the [`docs/`](docs/) directory).
54
+
52
55
 
53
56
  <br clear="left"/>
54
57
 
@@ -189,6 +192,31 @@ Include a directory tree as context:
189
192
  eva ask "Where should I add a new provider?" --dir src/eva
190
193
  ```
191
194
 
195
+ Pack an entire repository as context (up to provider token budget):
196
+
197
+ ```bash
198
+ eva ask "Explain the overall architecture" --repo . --dry-run
199
+ eva ask "Find potential bugs across the codebase" --repo . --yes
200
+ ```
201
+
202
+ Agentic repo exploration (Codex-style multi-turn tool calling):
203
+
204
+ ```bash
205
+ eva investigate "Find how CLI commands are wired and explain the app flow" . --yes
206
+ ```
207
+
208
+ #### `eva investigate` vs `eva ask --repo`
209
+
210
+ | Feature | `eva ask --repo` | `eva investigate` |
211
+ | :--- | :--- | :--- |
212
+ | **Approach** | Single-pass context dump | Multi-turn iterative tool calling |
213
+ | **Context Selection** | Query-blind (dependency centrality, file size) | Query-driven (model decides what to inspect) |
214
+ | **Tool Calling** | None | Iteratively calls `list_directory`, `read_file`, `search_code` |
215
+ | **Token Usage** | Pre-packs files up to token budget | Reads only files needed for the query |
216
+ | **Supported Providers** | All providers | Tool-capable providers (`groq`, `openrouter`, `opencode_zen`, `gemini`) |
217
+
218
+
219
+
192
220
  Explain a file or directory:
193
221
 
194
222
  ```bash
@@ -198,7 +226,7 @@ eva explain src/eva/router
198
226
  Analyze piped output:
199
227
 
200
228
  ```bash
201
- pytest -q | eva analyse "Summarize the failures"
229
+ pytest -q | eva analyze "Summarize the failures"
202
230
  ```
203
231
 
204
232
  Start an interactive chat session:
@@ -251,9 +279,9 @@ eva tree src/eva
251
279
 
252
280
  | Command | Purpose |
253
281
  | --- | --- |
254
- | `eva ask` | Ask a one-shot question, optionally with file or directory context. |
282
+ | `eva ask` | Ask a one-shot question, optionally with file, directory, or repo-wide packed context (`--repo`, `--dry-run`, `--yes`). |
255
283
  | `eva explain` | Explain a file, concept, or repository (with stack detection & module dependency graph). |
256
- | `eva analyse` / `eva analyze` | Analyze piped terminal output. |
284
+ | `eva analyze` | Analyze piped terminal output. |
257
285
  | `eva chat` | Run an interactive chat session, optionally saved and resumed. |
258
286
  | `eva work` | Generate and optionally execute a single safe local command. |
259
287
  | `eva edit` | Generate a unified diff for one or more files. |
@@ -402,6 +430,7 @@ Run the same checks in CI by pushing to a branch or opening a pull request. See
402
430
 
403
431
  ## Project files
404
432
 
433
+ - [`docs`](docs) — documentation suite ([eva-cli.vercel.app/docs](https://eva-cli.vercel.app/docs)).
405
434
  - [`pyproject.toml`](pyproject.toml) — package metadata, dependencies, and tooling.
406
435
  - [`CHANGELOG.md`](CHANGELOG.md) — release history.
407
436
  - [`LICENSE`](LICENSE) — MIT license.
@@ -4,6 +4,7 @@
4
4
 
5
5
  <p align="center">
6
6
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white"></a>
7
+ <a href="https://eva-cli.vercel.app/docs"><img src="https://img.shields.io/badge/Docs-eva--cli.vercel.app%2Fdocs-000000?style=for-the-badge&logo=vercel&logoColor=white"></a>
7
8
  <a href="LICENSE"><img src="https://img.shields.io/github/license/rootagi/eva?style=for-the-badge"></a>
8
9
  <a href="https://github.com/rootagi/eva/actions"><img src="https://img.shields.io/github/actions/workflow/status/rootagi/eva/ci.yaml?style=for-the-badge&label=Build"></a>
9
10
  <a href="#usage"><img src="https://img.shields.io/badge/CLI-Terminal-111827?style=for-the-badge&logo=gnubash&logoColor=white"></a>
@@ -17,6 +18,8 @@ Eva is a command line intelligence assistant. It uses deterministic local tools
17
18
 
18
19
  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"
19
20
 
21
+ 📖 **Website & Documentation**: Full interactive documentation is available at [eva-cli.vercel.app/docs](https://eva-cli.vercel.app/docs) (or offline in the [`docs/`](docs/) directory).
22
+
20
23
 
21
24
  <br clear="left"/>
22
25
 
@@ -157,6 +160,31 @@ Include a directory tree as context:
157
160
  eva ask "Where should I add a new provider?" --dir src/eva
158
161
  ```
159
162
 
163
+ Pack an entire repository as context (up to provider token budget):
164
+
165
+ ```bash
166
+ eva ask "Explain the overall architecture" --repo . --dry-run
167
+ eva ask "Find potential bugs across the codebase" --repo . --yes
168
+ ```
169
+
170
+ Agentic repo exploration (Codex-style multi-turn tool calling):
171
+
172
+ ```bash
173
+ eva investigate "Find how CLI commands are wired and explain the app flow" . --yes
174
+ ```
175
+
176
+ #### `eva investigate` vs `eva ask --repo`
177
+
178
+ | Feature | `eva ask --repo` | `eva investigate` |
179
+ | :--- | :--- | :--- |
180
+ | **Approach** | Single-pass context dump | Multi-turn iterative tool calling |
181
+ | **Context Selection** | Query-blind (dependency centrality, file size) | Query-driven (model decides what to inspect) |
182
+ | **Tool Calling** | None | Iteratively calls `list_directory`, `read_file`, `search_code` |
183
+ | **Token Usage** | Pre-packs files up to token budget | Reads only files needed for the query |
184
+ | **Supported Providers** | All providers | Tool-capable providers (`groq`, `openrouter`, `opencode_zen`, `gemini`) |
185
+
186
+
187
+
160
188
  Explain a file or directory:
161
189
 
162
190
  ```bash
@@ -166,7 +194,7 @@ eva explain src/eva/router
166
194
  Analyze piped output:
167
195
 
168
196
  ```bash
169
- pytest -q | eva analyse "Summarize the failures"
197
+ pytest -q | eva analyze "Summarize the failures"
170
198
  ```
171
199
 
172
200
  Start an interactive chat session:
@@ -219,9 +247,9 @@ eva tree src/eva
219
247
 
220
248
  | Command | Purpose |
221
249
  | --- | --- |
222
- | `eva ask` | Ask a one-shot question, optionally with file or directory context. |
250
+ | `eva ask` | Ask a one-shot question, optionally with file, directory, or repo-wide packed context (`--repo`, `--dry-run`, `--yes`). |
223
251
  | `eva explain` | Explain a file, concept, or repository (with stack detection & module dependency graph). |
224
- | `eva analyse` / `eva analyze` | Analyze piped terminal output. |
252
+ | `eva analyze` | Analyze piped terminal output. |
225
253
  | `eva chat` | Run an interactive chat session, optionally saved and resumed. |
226
254
  | `eva work` | Generate and optionally execute a single safe local command. |
227
255
  | `eva edit` | Generate a unified diff for one or more files. |
@@ -370,6 +398,7 @@ Run the same checks in CI by pushing to a branch or opening a pull request. See
370
398
 
371
399
  ## Project files
372
400
 
401
+ - [`docs`](docs) — documentation suite ([eva-cli.vercel.app/docs](https://eva-cli.vercel.app/docs)).
373
402
  - [`pyproject.toml`](pyproject.toml) — package metadata, dependencies, and tooling.
374
403
  - [`CHANGELOG.md`](CHANGELOG.md) — release history.
375
404
  - [`LICENSE`](LICENSE) — MIT license.
@@ -0,0 +1,19 @@
1
+ # Eva CLI Documentation
2
+
3
+ This directory contains the official documentation for Eva CLI, mirroring the content available at the [Eva website](https://eva-cli.vercel.app).
4
+
5
+ ## Contents
6
+
7
+ | Document | Description |
8
+ | --- | --- |
9
+ | [Getting Started](index.md) | Installation, setup, and key features overview. |
10
+ | [Command Reference](command-reference.md) | Complete CLI command reference with examples. |
11
+ | [Configuration](configuration.md) | Provider setup, environment variables, config.toml, and health diagnostics. |
12
+ | [Security & Hardening](security-model.md) | Secret redaction, audit logging, command safety, and sandbox controls. |
13
+ | [Provider Behavior](provider-behavior.md) | Provider routing, fallback strategy, caching, and offline tokenization. |
14
+ | [Architecture](architecture.md) | Module layout, request flow diagrams, and execution pipeline. |
15
+ | [Plugin System](plugins.md) | Writing plugins, entry points, lifecycle hooks, and fail-soft safety. |
16
+
17
+ ## Version
18
+
19
+ This documentation corresponds to **Eva CLI v4.1.0**.
@@ -0,0 +1,94 @@
1
+ # Architecture & Request Flow
2
+
3
+ This document details the modular architecture of Eva (`src/eva/`) and traces the request flow from CLI invocation down to sandboxed command execution.
4
+
5
+ ---
6
+
7
+ ## Request Flow Architecture
8
+
9
+ The sequence diagram below illustrates the end-to-end request flow for a command execution query (`eva work`):
10
+
11
+ ```mermaid
12
+ sequenceDiagram
13
+ autonumber
14
+ actor User
15
+ participant CLI as cli/app.py (Typer)
16
+ participant PLG as plugins/ (Loader)
17
+ participant WF as workflows/ (Engine)
18
+ participant PR as providers/ (Router)
19
+ participant SEC as security/work_safety.py
20
+ participant SBX as security/sandbox.py
21
+
22
+ User->>CLI: Invokes command ("eva work")
23
+ CLI->>PLG: Load & register plugins
24
+ PLG-->>CLI: Plugins registered (fail-soft)
25
+ CLI->>WF: Dispatch command payload & flags
26
+ WF->>PR: Request LLM candidate command generation
27
+ PR-->>WF: Return generated command string
28
+ WF->>SEC: Validate command safety & redaction
29
+ SEC->>SEC: Run SHA-256 Hash Audit Logging
30
+ alt Command Passed Safety Check
31
+ SEC->>SBX: Execute in isolated subprocess (shell=False)
32
+ SBX-->>User: Stream execution output to terminal
33
+ else Command Blocked / Denied
34
+ SEC-->>User: Report safety block & audit trail record
35
+ end
36
+ ```
37
+
38
+ ---
39
+
40
+ ## Component Layout (`src/eva/`)
41
+
42
+ Eva is structured into decoupled Python sub-modules:
43
+
44
+ | Directory | Responsibilities |
45
+ | --- | --- |
46
+ | `cli/` | Typer CLI entry points, argument parsing, shell completion, interactive terminal UI prompts. |
47
+ | `plugins/` | Plugin discovery via `importlib.metadata.entry_points`, `EvaPlugin` protocol, fail-soft loader. |
48
+ | `workflows/` | Declarative multi-step engine, session state machine, prompt assembly. |
49
+ | `providers/` | Multi-provider router (Groq, OpenRouter, Gemini, OpenCode Zen, Ollama, llama.cpp), fallback handler. |
50
+ | `security/` | Secret redaction (`work_safety.py`), entropy analysis, SHA-256 audit logger, subprocess sandbox (`sandbox.py`). |
51
+ | `indexing/` | `.gitignore`-aware file collector, directory tree generator, local search, offline tokenizer. |
52
+ | `cache/` | Disk-backed response caching and SHA-256 digest lookup. |
53
+ | `workspace/` | Session workspace management, notes, bookmarks, and activity logs. |
54
+ | `replay/` | Terminal session recorder and player with secret redaction. |
55
+ | `telemetry/` | Anonymized latency/error metrics collector (disabled by default). |
56
+
57
+ ---
58
+
59
+ ## Plugin Discovery & Lifecycle
60
+
61
+ Eva discovers plugins at startup via Python's `importlib.metadata.entry_points` under the group `"eva.plugins"`. Each plugin must:
62
+
63
+ 1. Subclass `EvaPlugin` from `eva.plugins`.
64
+ 2. Register an entry point in `pyproject.toml` under `[project.entry-points."eva.plugins"]`.
65
+ 3. Implement optional lifecycle hooks: `register_commands()`, `register_providers()`, `register_workflow_hooks()`.
66
+
67
+ Broken plugins log a warning and are skipped without crashing CLI startup (fail-soft safety).
68
+
69
+ ---
70
+
71
+ ## Detailed Execution Pipeline
72
+
73
+ 1. **CLI Parsing (`cli/app.py`)**:
74
+ Typer handles option flags (`--dry-run`, `--dry-run-explain`, `--allow-shell-features`, `--file`), validates input arguments, and delegates logic to the workflow engine.
75
+
76
+ 2. **Plugin Loading (`plugins/loader.py`)**:
77
+ All installed plugins are discovered and their commands, providers, and hooks are registered.
78
+
79
+ 3. **Workflow & Prompt Assembly (`workflows/`)**:
80
+ Context collector reads requested files/directories while skipping `.gitignore` matches and heavy binary assets. Assembles the final prompt with safety instructions.
81
+
82
+ 4. **Provider Fallback Routing (`providers/`)**:
83
+ The provider router queries the primary backend (e.g. Groq). If a rate limit or network error occurs, it sequentially tries fallback backends until a valid response is generated.
84
+
85
+ 5. **Security Verification (`security/work_safety.py`)**:
86
+ Extracted command undergoes:
87
+ - Secret/token redaction scan.
88
+ - Argv shlex syntax verification (`shell=False`).
89
+ - Blast-radius denylist check (`rm -rf /`, `mkfs`, `dd`).
90
+ - Opt-in allowlist check (`allowed_command_prefixes`).
91
+ - SHA-256 hash-chained audit logging (`~/.config/eva/command_audit.jsonl`).
92
+
93
+ 6. **Sandboxed Subprocess Execution (`security/sandbox.py`)**:
94
+ If user approves execution, the command runs in an isolated subprocess with environment variable sanitization, `stdin=DEVNULL`, and a strict 30-second timeout.
@@ -0,0 +1,197 @@
1
+ # Command Reference
2
+
3
+ Eva provides a suite of natural language and deterministic local commands. Below is the comprehensive command reference.
4
+
5
+ ---
6
+
7
+ ## AI Intelligence Commands
8
+
9
+ ### `eva ask`
10
+ Ask a one-shot question to the LLM, optionally passing local files or directories as context.
11
+
12
+ ```bash
13
+ # Basic question
14
+ eva ask "Explain the difference between a process and a thread"
15
+
16
+ # Include file context
17
+ eva ask "What does this module do?" --file src/eva/cli.py
18
+
19
+ # Include multiple file contexts
20
+ eva ask "Compare these modules" --file src/eva/cli.py --file src/eva/config.py
21
+
22
+ # Include directory context (respects .gitignore)
23
+ eva ask "Where should I add a new provider?" --dir src/eva
24
+
25
+ # Pack entire repository context up to provider budget (with dry-run summary)
26
+ eva ask "Explain codebase architecture" --repo . --dry-run
27
+
28
+ # Pack entire repository context and skip confirmation prompt
29
+ eva ask "Find architectural flaws" --repo . --yes
30
+
31
+ # Bypass response cache
32
+ eva ask "Why did this fail?" --no-cache
33
+ ```
34
+
35
+ ### `eva investigate`
36
+ 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.
37
+
38
+ ```bash
39
+ # Agentic repo investigation
40
+ eva investigate "Find how CLI commands are registered and explain the app flow" . --yes
41
+
42
+ # Custom turn cap and provider
43
+ eva investigate "Trace where budget limits are checked" . --max-turns 10 --provider groq --yes
44
+ ```
45
+
46
+ #### Comparison: `eva investigate` vs `eva ask --repo`
47
+ | Feature | `eva ask --repo` | `eva investigate` |
48
+ | :--- | :--- | :--- |
49
+ | **Execution Model** | Single-pass context dump | Multi-turn iterative tool calling |
50
+ | **Context Selection** | Query-blind (dependency centrality, file size) | Query-driven (model decides what to read) |
51
+ | **Tool Calling** | None | `list_directory`, `read_file`, `search_code` |
52
+ | **Token Usage** | Pre-packs files up to token budget | Reads only files needed for the query |
53
+ | **Supported Providers** | All providers | Tool-capable providers (`groq`, `openrouter`, `opencode_zen`, `gemini`) |
54
+
55
+ ### `eva explain`
56
+ Explain a file, concept, or repository with automatic stack detection and module dependency graph extraction.
57
+
58
+ ```bash
59
+ eva explain src/eva/router
60
+ ```
61
+
62
+ ### `eva analyze`
63
+ Analyze piped terminal output from stdin. Useful for diagnostic analysis of test failures or build logs.
64
+
65
+ ```bash
66
+ pytest -q | eva analyze "Summarize the test failures and root cause"
67
+ ```
68
+
69
+ ### `eva chat`
70
+ Run an interactive session chat with persistent memory and session state.
71
+
72
+ ```bash
73
+ # Start or attach to a named chat session
74
+ eva chat --session refactor-router
75
+
76
+ # Resume a previous session
77
+ eva chat --session refactor-router --resume
78
+ ```
79
+
80
+ ### `eva work`
81
+ Generate and optionally execute a single safe local command from natural language input.
82
+
83
+ ```bash
84
+ # Dry run command generation with safety scan
85
+ eva work "list the largest files in this repository" --dry-run
86
+
87
+ # Full safety check transparency report
88
+ eva work "find all TODO comments" --dry-run-explain
89
+
90
+ # Re-enable shell feature evaluation (pipes / redirects)
91
+ eva work "find top memory using processes" --allow-shell-features
92
+ ```
93
+
94
+ ### `eva edit`
95
+ Generate a reviewable unified diff patch for one or more files based on desired modifications.
96
+
97
+ ```bash
98
+ # Generate patch
99
+ eva edit "add validation for empty provider names" --file src/eva/cli.py
100
+
101
+ # Apply generated patch directly after confirmation
102
+ eva edit "add validation for empty provider names" --file src/eva/cli.py --apply
103
+ ```
104
+
105
+ ---
106
+
107
+ ## Workflow & Workspace Management
108
+
109
+ ### `eva workflow`
110
+ Declarative multi-step YAML workflow execution with human approval gates.
111
+
112
+ | Subcommand | Description |
113
+ | --- | --- |
114
+ | `eva workflow run <name>` | Execute a declarative multi-step workflow step-by-step. |
115
+ | `eva workflow run <name> -y` | Auto-approve all steps (useful for piping / CI). |
116
+ | `eva workflow list` | List available built-in and custom user workflows. |
117
+ | `eva workflow show <name>` | Display workflow steps and commands without running them. |
118
+
119
+ ### `eva workspace`
120
+ Manage isolated session workspaces, notes, bookmarks, and activity tracking.
121
+
122
+ ```bash
123
+ eva workspace create feature-auth # Create isolated workspace
124
+ eva workspace switch feature-auth # Switch active workspace
125
+ eva workspace list # List all session workspaces
126
+ eva workspace note "Check JWT key" # Add note (auto-redacts secrets)
127
+ eva workspace bookmark src/auth.py # Bookmark file or URL
128
+ eva workspace show # Show workspace history & notes
129
+ ```
130
+
131
+ ### `eva replay`
132
+ Replay recorded terminal execution sessions with step controls.
133
+
134
+ ```bash
135
+ eva replay --list
136
+ eva replay session-2026-08-10
137
+ ```
138
+
139
+ ---
140
+
141
+ ## Git Intelligence Commands
142
+
143
+ ### `eva changes`
144
+ Explain unstaged or staged git diff changes.
145
+
146
+ ```bash
147
+ eva changes
148
+ eva changes --staged
149
+ ```
150
+
151
+ ### `eva commit-message`
152
+ Generate a concise, conventional git commit message from staged changes.
153
+
154
+ ```bash
155
+ git add .
156
+ eva commit-message
157
+ ```
158
+
159
+ ---
160
+
161
+ ## Deterministic Local Commands (Zero Quota)
162
+
163
+ These utility commands run 100% locally and consume no LLM provider quota.
164
+
165
+ | Command | Purpose |
166
+ | --- | --- |
167
+ | `eva find "<pattern>"` | Fast local file matching. |
168
+ | `eva tree [dir]` | Print a `.gitignore`-aware directory tree. |
169
+ | `eva usage` | View local provider RPM and RPD usage counters. |
170
+ | `eva cache clear` | Clear cached LLM response objects. |
171
+
172
+ ---
173
+
174
+ ## Configuration Commands
175
+
176
+ ```bash
177
+ eva config set-key <provider> # Store key in OS keyring
178
+ eva config remove-key <provider> # Remove key from OS keyring
179
+ eva config set-model <provider> <model> # Configure default model for provider
180
+ eva config doctor # Run diagnostic health check on environment
181
+ eva config allow-command <prefix> # Add command prefix to execution allowlist
182
+ eva config disallow-command <prefix> # Remove command prefix from execution allowlist
183
+ eva config import-allowlist <path> # Import allowlist from a file
184
+ ```
185
+
186
+ ---
187
+
188
+ ## Shell & Global Options
189
+
190
+ ```bash
191
+ eva --version # Print Eva version
192
+ eva --verbose ask "Why did this fail?" # Enable verbose diagnostics logging
193
+ eva --install-completion # Install shell completion (bash/zsh/fish)
194
+ eva --show-completion # Print shell completion script
195
+ ```
196
+
197
+ Verbose mode writes diagnostics to stderr and to Eva's log file.