envex-0.6.0 is not a library.
envx
A powerful and secure environment variable manager for developers, featuring an intuitive Terminal User Interface (TUI) and comprehensive command-line interface.
🎥 Introduction Video
📸 Screenshots
🌟 Features
- 🖥️ Interactive TUI: Beautiful terminal interface for easy environment variable management
- 🔍 Smart Search: Fast filtering and searching across all environment variables
- 📊 Source Tracking: Distinguish between System, User, Process, Shell, and Application variables
- 📝 Multi-line Support: Edit complex environment variables with proper multi-line support
- 🔄 Import/Export: Support for multiple formats (JSON, YAML, TOML, ENV)
- 📸 Snapshots & Profiles Feature Implementation: Save and restore variable states
- 📁 Project Configuration: Define required variables, defaults, and scripts for consistent team environments
- 👀 Watch Mode & Monitor: Monitor file changes and sync automatically, track environment modifications in real-time
- ⚡ Performance: Built with Rust for blazing-fast performance
- 🎨 Cross-platform: Works on Windows, macOS, and Linux
📦 Installation
From Source
Using Cargo
Pre-built Binaries
Download the latest release for your platform from the releases page.
🚀 Quick Start
Launch the TUI
# or
List all environment variables
Set a variable
Get a variable
📖 Command Line Usage
Overview
)
)
Core Commands
init - Initialize a new project with the setup wizard
The init command launches an interactive setup wizard that helps you configure your project's environment variables.
The wizard will:
- Detect your project type (Web App, Python, Rust/Go, Docker, Microservices, or Custom)
- Guide you through setting up environment variables with values
- Create profiles for different environments (development, testing, production, etc.)
- Generate
.envfiles for each profile - Set up team collaboration features
- Configure validation rules
- Import existing
.envfiles if found
Example Usage
# Run the interactive setup wizard
# Skip wizard and create minimal config
What the Wizard Creates
After running the wizard, you'll have:
-
Project Configuration (
.envx/config.yaml):- Required environment variables with descriptions
- Default values for common variables
- Validation rules and patterns
- Auto-load configuration for .env files
-
Environment Profiles:
- Separate profiles for development, testing, production, etc.
- Profile-specific variable values
- Easy switching between environments
-
.envFiles (optional):- Generated
.envfiles for each profile - Pre-populated with your configured values
- Ready to use with your application
- Generated
Example Wizard Flow
✨ Welcome to envx! Your intelligent environment variable companion
This setup wizard will help you:
📋 Define environment variables ─ Set up your project's environment
🚀 Create profiles ─ Configure dev, test, and production environments
📦 Import existing files ─ Seamlessly migrate from .env files
📝 Generate .env files ─ Create .env files for each profile
👥 Enable team features ─ Share configurations with your team
⏱️ Estimated time: 1-3 minutes
💡 Tip: Press ESC at any time to exit the wizard
Let's create the perfect setup for your project! 🎯
The wizard will guide you through:
- Selecting your project type
- Configuring environment variables with actual values
- Creating environment profiles with custom names if needed
- Setting up team features (optional)
- Configuring validation rules
After completion, the wizard will check if all required variables are set and provide guidance on next steps.
list - List environment variables
)
)
)
# List all variables
# List with a pattern
# List from specific source
get - Get a specific variable
<PATTERN> Variable )
)
set - Set an environment variable
<NAME> Variable
<VALUE> Variable
# Set for current session
# Set persistently (survives reboot)
delete - Remove an environment variable
)
<PATTERN> Variable
analyze - Analyze environment variables
)
path - Manage PATH variable
)
)
Import/Export Commands
export - Export variables to a file
<FILE> Output
)
)
)
)
import - Import variables from a file
<FILE> Input
)
)
# Import from JSON
# Import from YAML
# Import from .env file
profiles - Manage environment profiles
)
snapshots - Manage environment snapshots
)
# Create a snapshot before deployment
# Restore if something goes wrong
# Compare snapshots
project - Manage project-specific configuration
)
Usage Example
# Initialize a new project
# Add required variables
# Edit configuration
# Check if all required variables are set
# Apply configuration
# Run a project script
# Create a custom project file
# Apply configuration from custom file
# Check validation with custom file
# Edit custom configuration
# Add required variable to custom config
Example Configuration File
Here's what a typical .envx/config.yaml would look like:
name: my-web-app
description: Production web application
# Required environment variables
required:
- name: DATABASE_URL
description: PostgreSQL connection string
pattern: "^postgresql://.*"
example: "postgresql://user:pass@localhost/dbname"
- name: API_KEY
description: External API authentication key
- name: PORT
description: Server port number
pattern: "^[0-9]+$"
example: "3000"
# Default values (if not already set)
defaults:
NODE_ENV: development
LOG_LEVEL: info
PORT: "3000"
# Files to auto-load (in order)
auto_load:
- .env
- .env.local
- .env.${NODE_ENV}
# Profile to activate
profile: dev
# Scripts for common tasks
scripts:
dev:
description: Start development server
run: npm run dev
env:
NODE_ENV: development
DEBUG: "true"
test:
description: Run tests
run: npm test
env:
NODE_ENV: test
migrate:
description: Run database migrations
run: npm run migrate
# Validation rules
validation:
warn_unused: true
strict_names: true
patterns:
"*_URL": "^https?://.*"
"*_PORT": "^[0-9]{1,5}$"
# Create a snapshot before deployment
# Restore if something goes wrong
# Compare snapshots
rename - Rename environment variables (supports wildcards)
)
<PATTERN> Pattern )
<REPLACEMENT> New
Example Usage
# Rename single variable
# Rename with wildcards
# Dry run to preview changes
replace - Replace environment variable values
<PATTERN> Variable )
<VALUE> New
Example Usage
find-replace - Find and replace text within environment variable values
<SEARCH> Text
<REPLACEMENT> Text
)
Example Usage
# Find and replace text within values
# Preview changes
watch - Watch files for changes and auto-sync
)
)
)
)
Example Usage
# Watch .env file and apply changes to system
# Watch and sync system changes back to file
# Bidirectional sync
# Watch multiple files with patterns
# Watch with custom settings
monitor - Monitor environment variable changes (read-only)
)
)
)
)
Example Usage
# Monitor all environment variables
# Monitor specific variables
# Show only changes (hide static vars)
# Monitor with logging
# Monitor variables from specific source
📊 Dependency Tracking
The deps command helps you understand how environment variables are used across your codebase.
It can scan your source files to find variable usage, identify unused variables, and provide detailed usage statistics.
Scanning for Dependencies
Scan your project to find all environment variable usage:
# Scan current directory
# Scan specific directories
# Scan with custom ignore patterns
Show Variable Dependencies
Find where specific variables are used:
# Show usage of a specific variable
# Example output:
# 📊 Dependencies for 'DATABASE_URL':
# Found 3 usage(s):
#
# ╭──────────────────────┬──────┬─────────────────────────────────────╮
# │ File ┆ Line ┆ Context │
# ╞══════════════════════╪══════╪═════════════════════════════════════╡
# │ src/db/connection.js ┆ 15 ┆ const url = process.env.DATABASE_URL│
# │ config/database.py ┆ 8 ┆ db_url = os.getenv("DATABASE_URL") │
# │ scripts/migrate.sh ┆ 3 ┆ echo "Using DB: $DATABASE_URL" │
# ╰──────────────────────┴──────┴─────────────────────────────────────╯
Find Unused Variables
Identify environment variables that are defined but never used:
# Show all unused variables
# Or use the shorthand
# Example output:
# ⚠️ Found 2 unused environment variables:
# ╭─────────────┬────────────────┬─────────╮
# │ Variable ┆ Value ┆ Source │
# ╞═════════════╪════════════════╪═════════╡
# │ OLD_API_KEY ┆ sk-old-key... ┆ User │
# │ LEGACY_URL ┆ http://old... ┆ System │
# ╰─────────────┴────────────────┴─────────╯
Usage Statistics
Get insights into your environment variable usage patterns:
# Show usage statistics
# Sort by usage count (most used first)
# Example output:
# 📊 Environment Variable Usage Statistics:
#
# ╭──────┬─────────────────┬─────────────┬───────────╮
# │ Rank ┆ Variable ┆ Usage Count ┆ Frequency │
# ╞══════╪═════════════════╪═════════════╪═══════════╡
# │ 1 ┆ DATABASE_URL ┆ 12 ┆ 25.5% │
# │ 2 ┆ API_KEY ┆ 8 ┆ 17.0% │
# │ 3 ┆ NODE_ENV ┆ 6 ┆ 12.8% │
# ╰──────┴─────────────────┴─────────────┴───────────╯
Supported File Types
The dependency tracker scans the following file types:
- JavaScript/TypeScript:
.js,.jsx,.ts,.tsx,.mjs,.cjs - Python:
.py,.pyw - Rust:
.rs - Go:
.go - Java:
.java - C#:
.cs - C/C++:
.c,.cpp,.cc,.cxx,.h,.hpp - Ruby:
.rb - PHP:
.php - Shell Scripts:
.sh,.bash,.zsh,.fish - PowerShell:
.ps1,.psm1 - Batch:
.bat,.cmd - Makefiles:
Makefile,Makefile.*
Output Formats
All dependency commands support different output formats:
# Table format (default)
# JSON format for scripting
# Simple format for parsing
🗑️ Cleanup Unused Variables
Remove unused environment variables safely:
# Preview what would be removed (dry run)
# Remove unused variables with confirmation
# Remove without confirmation
# Keep certain patterns when cleaning
# Scan additional paths before cleanup
📝 Documentation Generation
Automatically generate documentation for your environment variables from your project configuration:
# Generate documentation to stdout
# Generate to a file
# Custom title
# Include only required variables
Example Generated Documentation
The docs command generates a markdown table with all your environment variables:
Note: Required variables are shown in bold. Sensitive values (containing keywords like KEY, SECRET, PASSWORD, TOKEN) are automatically masked for security.
Documentation Features
-
Automatic Discovery: Finds variables from:
- Required variables in
.envx/config.yaml - Default values in configuration
- Variables in auto-loaded
.envfiles
- Required variables in
-
Security: Automatically masks sensitive values
-
Sorting: Variables are sorted alphabetically
-
Markdown Format: Ready to include in your README or docs
Integration with Project Configuration
The documentation is generated from your .envx/config.yaml:
name: myapp
description: My Application
required:
- name: DATABASE_URL
description: PostgreSQL connection string
example: postgresql://user:pass@localhost:5432/dbname
- name: API_KEY
description: API key for external service
example: sk-1234567890abcdef
defaults:
NODE_ENV: development
PORT: "3000"
auto_load:
- .env
- .env.local
🎮 TUI Keyboard Shortcuts
Normal Mode
↑/↓orj/k- Navigate up/downPageUp/PageDown- Navigate by pageHome/End- Jump to first/last itemEnterorv- View variable details/- Enter search modea- Add new variablee- Edit selected variabled- Delete selected variabler- Refresh listq- Quit
Search Mode
Esc- Cancel searchEnter- Apply search
Edit Mode
Tab- Switch between name and value fieldsCtrl+Enter- Save changesEsc- Cancel editing
🔧 Configuration
envx stores its configuration in platform-specific locations:
- Windows:
%APPDATA%\envx\config.toml - macOS:
~/Library/Application Support/envx/config.toml - Linux:
~/.config/envx/config.toml
Example Configuration
[]
= "json"
= true
= 100
[]
= "dark"
= true
🏗️ Architecture
envx is built with a modular architecture:
- envx-core: Core functionality for environment variable management
- envx-cli: Command-line interface implementation
- envx-tui: Terminal User Interface
- envx: Main binary that ties everything together
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Development Setup
# Clone the repository
# Build the project
# Run tests
# Run with debug logging
RUST_LOG=debug
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
📊 Benchmarks
envx is designed for performance:
- List 1000+ variables: < 10ms
- Search through variables: < 5ms
- Import/Export operations: < 50ms for typical workloads
Debug Mode
Run with debug logging enabled:
RUST_LOG=debug
📧 Contact
- Author: Mikko Leppänen
- Email: mleppan23@gmail.com
- GitHub: @mikeleppane