Introducing env-run: Simple Streamlined Environment Management for Developers
Published: July 6, 2025
Managing environment variables across different deployment stages (development, staging, production) is a common challenge that every developer faces. env-run is a lightweight utility that simplifies environment management for Linux developers.
What is env-run?
env-run is a bash utility that allows you to:
Execute commands with environment-specific variables automatically loaded
Source environments into your current shell session
Layer configurations with base settings and environment-specific overrides
Manage secrets securely using Linux's built-in secret-tool
Key Features
🚀 Simple Command Execution
env-run dev npm start
env-run prod ./deploy.sh
env-run uat python manage.py migrate
🔄 Environment Sourcing
source <(env-run dev --export)
source <(env-run prod --export)
🏗️ Layered Configuration
base.env
- Shared variables across all environments{env}.env
- Environment-specific overridesAutomatic variable precedence handling
🔐 Secure Secret Management
Integrates with Linux's secret-tool
for secure credential storage:
secret-tool store --label='API Key' service env-vars key API_KEY_PROD
Getting Started
Installation
# Clone the repository
git clone https://github.com/nathanfox/env-run.git
cd env-run
# Copy to your PATH (example ~/bin if on your path)
mkdir -p ~/bin
cp env-run ~/bin/ # or anywhere in your PATH
chmod +x ~/bin/env-run
# Set up environment files
cp setup-envs-template.sh setup-envs.sh
# Edit setup-envs.sh with your desired environment variables
nano setup-envs.sh
# Run the setup script to create environment files
./setup-envs.sh
Basic Usage
# Run a command with development environment
env-run dev npm start
# Load production environment into current shell
source <(env-run prod --export)
# Deploy with production settings
env-run prod ./deploy.sh
Configuration Structure
Environment files are stored in ~/.config/env/
:
~/.config/env/
├── base.env # Shared variables
├── dev.env # Development overrides
├── uat.env # UAT/staging overrides
└── prod.env # Production overrides
Example Configuration
base.env:
cat > "$ENV_DIR/base.env" << EOF
# keys shared by all environments
# Add your common environment variables here
API_BASE_URL=https://api.example.com
LOG_LEVEL=info
SECRET_KEY=$(get_secret "SECRET_KEY" "your-fallback-secret")
EOF
dev.env:
cat > "$ENV_DIR/dev.env" << EOF
ASPNETCORE_ENVIRONMENT=Development
# Add your dev-specific environment variables here
API_BASE_URL=https://dev-api.example.com
LOG_LEVEL=debug
API_KEY=$(get_secret "API_KEY_DEV" "dev-api-key")
EOF
uat.env:
cat > "$ENV_DIR/uat.env" << EOF
ASPNETCORE_ENVIRONMENT=Staging
# Add your UAT-specific environment variables here
API_BASE_URL=https://uat-api.example.com
API_KEY=$(get_secret "API_KEY_UAT" "uat-api-key")
EOF
prod.env:
cat > "$ENV_DIR/prod.env" << EOF
ASPNETCORE_ENVIRONMENT=Production
# Add your prod-specific environment variables here
API_KEY=$(get_secret "API_KEY_PROD" "")
DATABASE_URL=$(get_secret "DATABASE_URL_PROD" "")
EOF
Quality Assurance
env-run comes with comprehensive testing:
Unit tests for core functionality
Integration tests for real-world usage
Setup script tests for environment creation
CI/CD ready test suites
Run tests with:
./test-env-run.sh # Test main utility
./test-setup-envs.sh # Test setup script
Open Source & Community
env-run is open source and available on GitHub:
📂 Repository: github.com/nathanfox/env-run
📚 Documentation: Complete README with examples
🧪 Testing: Comprehensive test suites
🤝 Contributing: Issues and PRs welcome