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 overrides

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