# kvenv - Secure .env while vibe coding with Azure Key Vault

kvenv is a command-line tool to securely manage environment variables by fetching secrets from Azure Key Vault based on references in a `.env` file.

Avoid storing sensitive information in `.env` files by referencing secrets stored securely in Azure Key Vault. kvenv reads a `.env` file, fetches secrets from Key Vault as needed, and runs the specified command with those environment variables set. 

This avoids secret leakage while vibe coding and prevents LLMs from seeing sensitive secrets in your local development environment while still using environment variables in your applications or scripts.

It is inspired in 1password's `op run` command for securely injecting secrets into environment variables.

## Installation

```bash
pip install kvenv
```

### Usage

Create a `.env` file referencing your Key Vault secrets:

```
# .env
# Explicitly specify vault
DATABASE_URL=kv://my-key-vault/DATABASE-URL
API_KEY=kv://my-key-vault/API-KEY
# Use default vault from KEYVAULT env var or with -v 
TOKEN_ID=kv://TOKEN-ID
DEBUG=true
```

Then prepend the kvenv command to your usual command:

```bash
# Uses .env and default vault from KEYVAULT environment variable
KEYVAULT=my-kv kvenv -- npm run dev

# You can specify a different .env file name or a default vault
kvenv -e .env.ref -v my-kv -- npm run dev

# --env-file or -e : specify .env file (default: .env)


# Python example 
kvenv -- python app.py

# Rails example
kvenv -- rails server

# Per-secret vault override inside file
# DATABASE_URL=kv://some-kv/DATABASE-URL
```

## Supported .env File Format

- Lines: `KEY=VALUE`
- Comments: lines starting with `#` (optionally preceded by whitespace)
- Blank lines allowed
- Optional leading `export ` supported
- Quoted values supported: `"..."` or `'...'`
- VALUE may contain `=`

### Key Vault References

```
# Use default vault (via KEYVAULT env var or -v flag)
DATABASE_URL=kv://DATABASE-URL

# Specify vault explicitly
API_KEY=kv://my-other-vault/API-KEY

# Non kv:// values are passed through unchanged
DEBUG=true
```

## Requirements

- Azure CLI installed (`az`)
- You are authenticated: `az login`
- Access to Key Vault secrets (get permission)

## Development

### Clone the Repository

```bash
git clone https://github.com/merlos/kvenv.git
cd kvenv
```

### Install in Development Mode

```bash
# Install package in editable mode with dev dependencies
pip install -e ".[dev]"
```

### Run Tests

```bash
# Run all tests
pytest

# Run with verbose output
pytest -v

# Run with coverage
pytest --cov=kvenv --cov-report=term-missing
```

### Testing the CLI

After installing in development mode, you can test the `kvenv` command directly:

```bash
# Create a test .env file
echo "FOO=bar" > test.env

# Run a command with the environment
kvenv -e test.env -- env | grep FOO
```

## License
Distributed under MIT License Copyright (c) 2026 @merlos


