Metadata-Version: 2.4
Name: envbot
Version: 1.1.0
Summary: Local AI-powered environment variable search assistant
Home-page: https://github.com/ravindraogg/envbot
Author: Ravindra S
Author-email: 
Project-URL: Portfolio, https://ravindraogg.netlify.app/?utm_source=pypi&utm_medium=package&utm_campaign=envbot
Project-URL: Source, https://github.com/ravindraogg/envbot
Project-URL: Bug Tracker, https://github.com/ravindraogg/envbot/issues
Keywords: env environment variables search ai faiss semantic dotenv cli
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastembed>=0.5.0
Requires-Dist: faiss-cpu>=1.8.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: numpy<3.0.0,>=1.26.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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:

```bash
pip uninstall envbot
```

### Install with pipx (Recommended)

[pipx](https://pipx.pypa.io/) installs CLI tools in isolated environments and makes them globally available:

```bash
pipx install envbot
```

After installation, verify envbot is on your PATH:

```bash
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)

```bash
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:

```bash
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

```bash
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

```bash
envbot "openai api key"
```

### Show Variable Values (`-v`)

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

```bash
envbot -v "stripe"
```

### Show Source File Path (`--show-source`)

See which `.env` file each variable came from:

```bash
envbot --show-source "database"
```

### Change Number of Results (`-k`)

By default, 3 results are returned. Get more:

```bash
envbot -k 10 "api key"
```

### Combine All Flags

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

### Rebuild the Index

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

```bash
envbot --reindex
```

### View Help

```bash
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`:

```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:

```bash
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](LICENSE) for details.

---

## Author

Built by **Ravindra S** -- [ravindraogg.netlify.app](https://ravindraogg.netlify.app/?utm_source=pypi&utm_medium=package&utm_campaign=envbot)
