envy-secrets 2.0.0

Git for your .env files - Secure environment variable management with encryption

🔐 Envy

Git for your .env files - Secure environment variable management with encryption, profiles, and team collaboration

Installation • Quick Start • Documentation • Cloud Sync • Contributing

---

📋 Table of Contents

• Features
• Installation
• Quick Start
• Commands
  • Core Commands
  • Profile Commands
  • Team Commands
• Use Cases
• Security Best Practices
• File Structure
• FAQ
• Contributing
• Roadmap
• License

Features

🔒 Security First

• AES Encryption - All secrets stored encrypted using Fernet (AES-256)
• System Keyring Integration - Master key stored in OS keychain (Windows Credential Manager, macOS Keychain)
• Process Injection - envy run injects secrets into memory, never writes to disk
• Age Encryption - Public key sharing for team collaboration

📁 Profile Management

• Multiple environments (dev, staging, prod)
• Easy switching between profiles
• Copy and diff profiles

🔄 Drift Detection

• Compare profiles to find missing keys
• Prevent "works on my machine" errors

⏰ Secret Rotation

• Set expiration dates on secrets
• Automatic staleness detection
• Health checks for your secrets

Installation

# Install from PyPI
pip install envy-secrets

PyPI: https://pypi.org/project/envy-secrets/

Development Installation

# Create and activate virtual environment
python -m venv venv
.\venv\Scripts\Activate  # Windows
source venv/bin/activate  # Linux/macOS

# Install in development mode
pip install -e .

Quick Start

# Initialize envy in your project
envy init

# Set some secrets
envy set DATABASE_URL=postgres://localhost/mydb
envy set API_KEY=sk-1234567890 --expires 30d
envy set PORT=3000 --profile prod

# View secrets
envy view
envy view --profile prod --show

# Run your app with secrets injected (RECOMMENDED!)
envy run dev -- node index.js
envy run prod -- python app.py

# Generate .env file (less secure, but sometimes needed)
envy export --output .env.local

# Login to Envy Cloud (for team collaboration)
envy cloud login
envy cloud status  # Check who you're logged in as

Commands

Core Commands

Command	Description
envy init	Initialize envy in the current directory
envy set KEY=VALUE	Set an encrypted environment variable
envy get KEY	Get a variable value
envy delete KEY	Delete a variable
envy view	View all secrets in a profile
envy run <profile> -- <command>	Run command with secrets injected
envy export	Generate a .env file
envy import	Import from a .env file
envy capture	Capture current process environment
envy diff <source> <target>	Show differences between profiles
envy check	Check for expired/stale secrets
envy status	Show envy status

Profile Commands

Command	Description
envy profile list	List all profiles
envy profile create <name>	Create a new profile
envy profile delete <name>	Delete a profile
envy profile switch <name>	Switch active profile
envy profile copy <src> <dst>	Copy secrets between profiles

Team Commands

Command	Description
envy cloud login	Login to Envy Cloud
envy cloud logout	Logout from Envy Cloud
envy cloud status	Show logged-in user info
envy cloud clone <slug>	Clone a project from cloud
envy cloud push	Push local secrets to cloud
envy cloud remote	Show/set remote project
envy cloud remote add <project-slug>	Set a remote project
envy team list	List team members from cloud

💡 Use Cases

Local Development

# Developer A sets up the project
envy init
envy set DATABASE_URL=postgres://localhost/dev
envy set API_KEY=dev-key-123
envy run dev -- npm start

# Developer B clones and gets secrets
git clone repo
envy cloud login
envy cloud clone myproject development
envy run dev -- npm start

Multiple Environments

# Create separate profiles for each environment
envy profile create staging
envy profile create prod

# Set environment-specific secrets
envy set DATABASE_URL=postgres://dev-db --profile dev
envy set DATABASE_URL=postgres://staging-db --profile staging
envy set DATABASE_URL=postgres://prod-db --profile prod

# Run in different environments
envy run dev -- python app.py
envy run staging -- python app.py
envy run prod -- python app.py

CI/CD Integration

# In your CI/CD pipeline
pip install envy-secrets
envy cloud login --token $ENVY_TOKEN
envy cloud clone myproject production
envy export --output .env
# Run your build/deploy commands

Secret Rotation

# Set secrets with expiration
envy set API_KEY=old-key-123 --expires 30d

# Check for expiring secrets
envy check

# Rotate the secret
envy set API_KEY=new-key-456 --expires 30d

Security Best Practices

1. Never commit .envy/master.key - It's automatically added to .gitignore
2. Use envy run instead of envy export - Secrets stay in memory
3. Set expiration dates - envy set KEY=value --expires 30d
4. Run envy check regularly - Find stale and expiring secrets

File Structure

your-project/
├── .envy/
│   ├── master.key      # 🔑 Encryption key (NEVER COMMIT!)
│   └── secrets.json    # 🔒 Encrypted secrets (safe to commit)
├── .gitignore          # Auto-updated to ignore sensitive files
└── ...

❓ FAQ

How is this different from dotenv?

Envy encrypts your secrets and stores them securely, while dotenv just loads plain-text .env files. Envy also supports:

• Multiple environments (profiles)
• Cloud sync for teams
• Secret expiration tracking
• Process injection (secrets never touch disk)

Can I use this with my existing .env files?

Yes! Use envy import to import your existing .env file:

envy import .env

What happens if I lose my master key?

Without the master key (stored in .envy/master.key), your secrets cannot be decrypted. Always back up this file securely or use cloud sync to share secrets with your team.

Is it safe to commit .envy/secrets.json?

Yes! The secrets.json file contains only encrypted data. Without the master key, it cannot be decrypted.

How do I share secrets with my team?

Use Envy Cloud:

envy cloud login
envy cloud push
# Team members can then clone the project

Can I use this in production?

Yes! Use envy run prod -- your-command to inject secrets directly into your production process without writing them to disk.

What encryption does Envy use?

Envy uses Fernet (symmetric encryption) which is built on AES-256 in CBC mode with HMAC for authentication.

🤝 Contributing

We welcome contributions! Here's how you can help:

Setting Up Development Environment

# Clone the repository
git clone https://github.com/KRISHNA-JAIN15/ENVY.git
cd ENVY

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
.\venv\Scripts\Activate    # Windows

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
ruff check .

Contribution Guidelines

1. Fork the repository and create a new branch
2. Make your changes with clear commit messages
3. Add tests for new features
4. Ensure all tests pass with pytest
5. Format your code with black and ruff
6. Submit a pull request with a clear description

Report Issues

Found a bug or have a feature request? Open an issue on GitHub.

📄 License

MIT License - see the LICENSE file for details.

---

Made with ❤️ by Krishna Jain

⭐ Star us on GitHub • 🐦 Follow updates

Report Bug • Request Feature • Documentation