envbot 1.1.0

Local AI-powered environment variable search assistant

envbot

Local AI-powered environment variable search assistant.

Stop digging through dozens of .env files scattered across your projects. envbot indexes all your environment variables and lets you find them instantly using natural language search -- powered by sentence embeddings and FAISS.

envbot "mongodb connection string"

                                Search Results
+--------------------------------------------------------------------------+
|   # | Variable        | Value                        | Source            |
|-----+-----------------+------------------------------+-------------------|
|   1 | MONGO_URI       | mongodb+srv://user:pass@c... | D:\App\.env       |
|   2 | DATABASE_URL    | mongodb://localhost:27017/... | D:\Api\.env       |
|   3 | DB_CONNECTION   | mongodb://admin@cluster0...  | D:\Svc\.env       |
+--------------------------------------------------------------------------+
                           3 result(s) found

---

Features

• AI-Powered Semantic Search -- Understands what you mean, not just exact matches. Search for "stripe payment key" and it finds STRIPE_SECRET_KEY.
• Multi-Drive / Multi-Directory Scanning -- Scan one or more drives (Windows) or directories (macOS/Linux) in a single index.
• Cross-Platform -- Works on Windows, macOS, and Linux.
• Interactive Configuration Wizard -- No config files to edit manually. The CLI guides you through setup.
• Zero-Leak Security -- Variable values are never stored in the index. They are only read on-the-fly when you explicitly request them with -v.
• Beautiful CLI -- Rich terminal UI with progress bars, spinners, tables, and color-coded output.
• Fast -- FAISS vector search returns results in milliseconds after the initial model load.

---

Installation

Prerequisites

• Python 3.11+ is required.
• pipx (recommended) or pip (alternative).

Upgrade Note for Existing pip Users

If you previously installed envbot with pip, uninstall it first to avoid conflicts:

pip uninstall envbot

Install with pipx (Recommended)

pipx installs CLI tools in isolated environments and makes them globally available:

pipx install envbot

After installation, verify envbot is on your PATH:

envbot --help

If the command is not found, ensure pipx's binary directory is in your system PATH:

• Windows: %USERPROFILE%\.local\bin (or pipx ensurepath)
• macOS / Linux: ~/.local/bin (or pipx ensurepath)

Then restart your terminal.

Install with pip (Alternative)

pip install envbot

Note: On first run, envbot will automatically download the BAAI/bge-small-en-v1.5 embedding model (~30 MB). This happens only once.

---

Quick Start

Step 1: Configure & Index

Run the reindex command. The interactive wizard will guide you:

envbot --reindex

You will be prompted to:

1. Select drives/directories to scan -- Choose which drives (Windows: C, D, E) or directories (Linux/macOS: /home/user/projects) to scan for .env files.
2. Set storage path -- Choose where to store the copied .env files and the FAISS index. Defaults to ~/.envbot_data.

The wizard saves your preferences to ~/.envbot_config.json. On subsequent runs, it will ask if you want to reuse the saved configuration.

Step 2: Search

envbot "database"

That's it! You'll see a table of matching environment variable names.

---

Usage

All options must be placed before the search query.

Basic Search

envbot "openai api key"

Show Variable Values (-v)

Read and display the actual value from the .env file on-the-fly:

envbot -v "stripe"

Show Source File Path (--show-source)

See which .env file each variable came from:

envbot --show-source "database"

Change Number of Results (-k)

By default, 3 results are returned. Get more:

envbot -k 10 "api key"

Combine All Flags

envbot -v --show-source -k 5 "mongodb"

Rebuild the Index

Re-scan all configured drives and rebuild the search database:

envbot --reindex

View Help

envbot --help

---

How It Works

+------------------+     +------------------+     +------------------+
|  1. SCAN         | --> |  2. PARSE        | --> |  3. EMBED        |
|  Recursively     |     |  Extract variable |     |  Generate vector |
|  find .env files |     |  names (no values)|     |  embeddings via  |
|  across drives   |     |  from all files   |     |  SentenceTransf. |
+------------------+     +------------------+     +------------------+
                                                         |
                                                         v
+------------------+     +------------------+     +------------------+
|  6. DISPLAY      | <-- |  5. RANK         | <-- |  4. INDEX        |
|  Rich table with |     |  Cosine similar. |     |  Store vectors   |
|  colors & values |     |  via FAISS       |     |  in FAISS index  |
+------------------+     +------------------+     +------------------+

Architecture

File	Purpose
cli.py	Entry point, argument parsing, Rich UI rendering
scanner.py	Recursively walks drives/directories for .env files
parser.py	Extracts variable names from copied .env files
indexer.py	Generates embeddings and builds the FAISS vector index
search.py	Encodes queries and performs FAISS similarity search

Security Model

• Values are never stored in the FAISS index or metadata files.
• Only variable names and source file paths are persisted.
• When you use -v, values are read on-the-fly from the local copy at search time.
• Copied .env files are stored in your configured data directory (default: ~/.envbot_data/copied_envs/).

---

Configuration

Your configuration is stored at ~/.envbot_config.json:

{
  "scan_drives": ["D:\\", "E:\\"],
  "data_dir": "C:\\Users\\you\\.envbot_data"
}

Key	Description
scan_drives	List of drives (Windows) or directories to scan
data_dir	Where the index, metadata, and copies are stored

You can edit this file manually or re-run envbot --reindex to use the wizard.

---

Command Reference

Command	Description
envbot "query"	Search for matching variables
envbot -v "query"	Search and show values
envbot --show-source "query"	Search and show source file paths
envbot -k 10 "query"	Return up to 10 results
envbot -v --show-source -k 5 "query"	All flags combined
envbot --reindex	Configure drives and rebuild index
envbot --help	Show help message

---

Requirements

Package	Version	Purpose
fastembed	>= 0.5.0	Semantic text embeddings
faiss-cpu	>= 1.8.0	Vector similarity search
typer	>= 0.12.0	CLI framework
rich	>= 13.7.0	Terminal UI (tables, spinners)
numpy	>= 1.26.0	Numerical operations

---

Platform Support

Platform	Status	Drive/Path Format
Windows 10/11	Supported	C:\, D:\, E:\
macOS	Supported	/Users/you/projects
Linux	Supported	/home/you/projects

---

Troubleshooting

"FAISS index not found" error

You need to build the index first:

envbot --reindex

Slow first search

The first search takes a few seconds because the AI model needs to load into memory. Subsequent searches in the same session are instant.

Permission errors on Windows

If you see PermissionError: [WinError 5], make sure the storage path is set to a user-writable directory (the default ~/.envbot_data should work). Re-run envbot --reindex to reconfigure.

---

License

MIT License. See LICENSE for details.

---

Author

Built by Ravindra S -- ravindraogg.netlify.app