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.

Secret leakage during development occurs when AI coding assistants like GitHub Copilot, Cursor, or Claude Code read .env files containing passwords, tokens, or other sensitive information from your local environment. These tools may inadvertently expose secrets when providing code suggestions or autocompletion.

With kvenv, you avoid storing sensitive information directly in .env files by using Azure Key Vault references instead. Simply replace actual secret values with Key Vault URLs (like kv://my-vault/secret-name), and kvenv will automatically fetch the real secrets from Azure Key Vault when running your applications.

This approach gives you several advantages:

• Safe from AI assistants - When VSCode, Claude Code or Cursor reads your .env file, they only see references like kv://my-keyvault/api_key, not actual secrets

• No secrets in version control - You can safely commit your .env file because it only contains references

• Team sharing - Secrets are shared via key vaults, not copied between machines or sent through chat or email.

• Instant rotation - Update a secret in keyvault, and all team members get it immediately

• Audit trail - You get logs who accessed what secrets and when

pip install kvenv

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 argument
# That way you don't reveal the vault name in the .env file
TOKEN_ID=kv://TOKEN-ID

# Other env vars are passed through unchanged
DEBUG=true

Login to Azure if you haven't already:

az login 

Then prepend the kvenv command to your usual command:

# If .env is in the current directory
kvenv -- python app.py

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

# You can specify a different vault name also through the -v argument
kvenv -v my-prd-vault -- node server.js

# You can specify a different .env file name
kvenv -e .env-test -- python app.py


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

To test if the secret is being provisioned correctly, you can run:

kvenv -- env | grep DATABASE_URL

# you can also run without kvenv to see it is not set
env | grep DATABASE_URL

• 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 =

# 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

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

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

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

# Run all tests
pytest

# Run with verbose output
pytest -v

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

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

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

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

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

Distributed under MIT License Copyright (c) 2026 @merlos