envdiff / envset
Powerful CLI tools for comparing and editing environment configurations across local and remote systems
envdiff and envset are command-line tools that help you manage environment configurations across different file formats (.env, YAML, Python config.py) and locations (local files or remote servers via SSH).
✨ Features
envdiff — Compare & Patch
- 🔍 Compare environment configs between source and target files
- 📊 Detect missing, extra, and different keys
- 🔧 Generate patches in multiple formats (export, dotenv, PowerShell)
- ✅ CI/CD integration with
--checkflag (exits non-zero on differences) - 🎯 Filter keys with regex patterns (
--include/--exclude) - 📝 Apply changes directly to
.envfiles with automatic backups - 🌐 Remote support via SSH/SCP for both source and target
- 📋 JSON output for machine-readable reports
envset — Single Key Editor
- ✏️ Edit one key across multiple files simultaneously
- 📁 Multi-format support:
.env, YAML, Pythonconfig.py - 🔄 In-place rewriting for existing constants and dict assignments
- 🎯 Nested keys support for YAML and Python dicts (dot notation)
- 🌐 Remote editing via SSH/SCP
- 💾 Automatic backups before modifications
- 🔢 JSON values support for typed data
🚀 Quick Start
Installation
Option 1: pipx (Recommended for CLI tools)
pipx install envdiff-tool
Option 2: pip
pip install envdiff-tool
Option 3: From source
git clone https://github.com/talaatmagdyx/envdiff_fresh.git
cd envdiff_fresh
pip install -e .
Quick Example
# Compare YAML config with .env file
envdiff --source config.yml --target .env --patch-format export
# Set a key across multiple files
envset --files .env config.yml --key LOG_LEVEL --value warning
📖 Documentation
Table of Contents
- envdiff: Compare & Patch
- envset: Single Key Editor
- Remote Operations
- CI/CD Integration
- Advanced Usage
- Windows Support
- Development
🔍 envdiff: Compare & Patch
Compare environment configurations and generate patches to synchronize them.
Basic Usage
# Compare source YAML with target .env
envdiff --source examples/source.yml --target examples/target.env
# Output:
# Missing on target (2):
# - database.host
# - database.port
#
# Extra on target (2):
# - DATABASE_HOST
# - DATABASE_PORT
#
# Different values (2):
# - APP_MODE
# - FEATURE_X
Generate Patches
# Generate export format patch
envdiff --source examples/source.yml --target examples/target.env --patch-format export
# Output:
# # Patch (export) — apply on target to add/update keys
# export database.host='db.prod'
# export database.port='5432'
# export APP_MODE='production'
# export FEATURE_X='True'
Available patch formats:
export— Shell export statements (Bash/Zsh)dotenv— Standard.envformatpowershell— PowerShell environment variables
Apply Changes Directly
# Apply changes to target .env (creates backup automatically)
envdiff --source config.yml --target .env --apply
# Dry-run to preview changes
envdiff --source config.yml --target .env --apply --apply-dry-run
Filter Keys with Regex
# Only check keys starting with APP_
envdiff --source config.yml --target .env --include '^APP_'
# Exclude secret keys
envdiff --source config.yml --target .env --exclude 'SECRET|PASSWORD|KEY'
# Combine filters
envdiff --source config.yml --target .env \
--include '^APP_' \
--exclude 'SECRET'
Prefix Filtering
# Only compare keys with specific prefix
envdiff --source config.yml --target .env --only-prefix DATABASE
# Ignore keys with specific prefix
envdiff --source config.yml --target .env --ignore-prefix DEBUG
JSON Output
Get machine-readable output for automation:
envdiff --source config.yml --target .env --format json
# Output:
# {
# "source": "config.yml",
# "target": ".env",
# "summary": {
# "missing": 2,
# "extra": 1,
# "different": 1,
# "same": 5
# },
# "keys": {
# "missing": ["APP_NAME", "API_KEY"],
# "extra": ["OLD_KEY"],
# "different": ["DATABASE_URL"]
# },
# "patch": {
# "format": "export",
# "lines": ["export APP_NAME='myapp'", ...]
# }
# }
Case Sensitivity
# Case-insensitive comparison (default)
envdiff --source config.yml --target .env --case-sensitive false
# Case-sensitive comparison
envdiff --source config.yml --target .env --case-sensitive true
✏️ envset: Single Key Editor
Edit a single key across multiple files in different formats.
Basic Usage
# Set LOG_LEVEL in multiple files
envset --files .env config.yml --key LOG_LEVEL --value warning
Supported File Types
.env Files
envset --files .env --key DATABASE_URL --value postgres://localhost/db
YAML Files (Nested Keys)
# Set nested key using dot notation
envset --files config.yml --key app.database.host --value db.example.com
# Set with JSON value (for typed data)
envset --files config.yml --key app.timeout --value '30' --json
Python config.py Files
UPPERCASE Constants:
# Add or update a constant
envset --files config.py --key RABBITMQ_USER --value admin
# In-place rewrite existing constant
envset --files config.py --key RABBITMQ_USER --value root --rewrite
CONFIG/ENV Dictionaries:
# Set nested dict key
envset --files config.py --key database.host --value db.new
# In-place rewrite existing dict assignment
envset --files config.py --key database.host --value db.new --rewrite
Multiple Files
# Update the same key across multiple files
envset --files .env config.yml config.py \
--key API_KEY \
--value "new-secret-key"
JSON Values
# Set complex JSON values
envset --files config.yml \
--key app.features \
--value '{"feature1": true, "feature2": false}' \
--json
Dry Run
# Preview changes without modifying files
envset --files config.py --key RABBITMQ_USER --value admin --dry-run
🌐 Remote Operations
Both tools support remote files via SSH/SCP.
SSH Configuration
# Basic remote path
envdiff --source user@server:/path/to/config.yml --target .env
# With SSH port
envdiff --source user@server:/path/config.yml \
--target .env \
--source-ssh-port 2222
# With SSH identity file
envdiff --source user@server:/path/config.yml \
--target .env \
--source-ssh-identity ~/.ssh/id_rsa
# With SSH options
envdiff --source user@server:/path/config.yml \
--target .env \
--source-ssh-extra "StrictHostKeyChecking=no,UserKnownHostsFile=/dev/null"
Remote Examples
# Compare local YAML with remote .env
envdiff --source config.yml --target user@prod:/srv/app/.env
# Set key on remote config.py
envset --files user@prod:/opt/app/config.py \
--key RABBITMQ_USER \
--value root \
--rewrite
# Apply changes to remote .env
envdiff --source config.yml \
--target user@prod:/srv/app/.env \
--apply
🔄 CI/CD Integration
Use --check flag to fail CI builds when configurations don't match.
Basic CI Check
# Exit with code 5 if differences exist
envdiff --source config.yml --target .env --check
# In CI script
if ! envdiff --source config.yml --target .env --check; then
echo "Configuration mismatch detected!"
exit 1
fi
With Filters
# Only check specific keys
envdiff --source config.yml --target .env \
--include '^APP_' \
--check
JSON Output for CI
# Get structured output for CI scripts
envdiff --source config.yml --target .env \
--format json \
--check \
--patch-format export
# Exit code 5 if differences remain after filtering
GitHub Actions Example
- name: Check environment configuration
run: |
envdiff \
--source config/production.yml \
--target .env \
--include '^APP_' \
--exclude 'SECRET' \
--check \
--format json
🎯 Advanced Usage
Custom Source/Target Types
# Explicitly specify file types
envdiff --source config.yml \
--target config.py \
--source-type yaml \
--target-type py
Show Same Values
# Include keys with matching values in output
envdiff --source config.yml --target .env --show-same
Keys-Only JSON Output
# Get only the keys JSON (without full report)
envdiff --source examples/source.yml --target examples/target.env --keys-json
# Output (JSON followed by text summary):
# {
# "missing": ["database.host", "database.port"],
# "extra": ["DATABASE_HOST", "DATABASE_PORT"],
# "different": ["APP_MODE", "FEATURE_X"],
# "same": null
# }
JSON-Only Mode
# Output only JSON (no human-readable text)
envdiff --source config.yml --target .env --json-only
Backup Control
# Disable automatic backups
envdiff --source config.yml --target .env --apply --apply-backup none
# Backups are enabled by default (format: .env.bak-20240101120000)
🪟 Windows Support
Installation
# Install with pipx
pipx install envdiff-tool
# If pipx is not on PATH, add it:
$Env:Path += ';' + (python -m site --user-base) + '\Scripts'
PowerShell Patch Format
# Generate PowerShell patch
envdiff --source .\config.yml --target .\.env --patch-format powershell > patch.ps1
# Review and apply
Get-Content patch.ps1
. .\patch.ps1
Remote Operations from Windows
Windows 10+ includes OpenSSH, so remote operations work out of the box:
# Compare with remote file
envdiff --source .\config.yml --target user@server:/srv/app/.env
# Edit remote config
envset --files user@server:/opt/app/config.py --key RABBITMQ_USER --value root
📁 File Format Examples
.env Format
APP_NAME=myapp
DATABASE_URL=postgres://localhost/db
LOG_LEVEL=info
YAML Format
app:
name: myapp
database:
url: postgres://localhost/db
logging:
level: info
Python config.py Format
# Constants
RABBITMQ_USER = 'admin'
API_KEY = 'secret-key'
# Or dictionaries
CONFIG = {
'database': {
'host': 'localhost',
'port': 5432
}
}
🛠️ Development
Setup
# Clone repository
git clone https://github.com/talaatmagdyx/envdiff_fresh.git
cd envdiff_fresh
# Install in editable mode with dev dependencies
pip install -e .[dev]
Running Tests
# Run all tests with coverage
pytest
# Tests require 100% coverage to pass
Linting
# Check code style
ruff check .
# Format code
ruff format .
# Check formatting without changes
ruff format --check .
Project Structure
envdiff_fresh/
├── envdiff.py # Main diff/patch tool
├── envset.py # Single key editor
├── tests/ # Test suite (100% coverage)
│ ├── test_cli_integration.py
│ ├── test_coverage.py
│ ├── test_envset_configpy.py
│ └── test_parsers_and_patch.py
├── examples/ # Example files
│ ├── example.env
│ ├── example.yaml
│ ├── source.yml
│ ├── target.env
│ └── target_config.py
├── pyproject.toml # Project configuration
├── requirements.txt # Runtime dependencies
└── README.md # This file
📝 Examples Directory
The examples/ directory contains sample files for testing:
example.env— Sample.envfileexample.yaml— Sample YAML configurationsource.yml— Source file for diff examplestarget.env— Target file for diff examplestarget_config.py— Python config file example
Try them out:
envdiff --source examples/source.yml --target examples/target.env
envset --files examples/example.env examples/example.yaml --key LOG_LEVEL --value debug
🚢 Release Process
This repository includes GitHub Actions workflows for automated releases.
Standard Release
- Bump version in
pyproject.toml - Commit and tag:
git add pyproject.toml git commit -m "chore: bump version to 0.1.1" git tag v0.1.1 git push --follow-tags
- GitHub Actions will:
- Build
sdistandwheelpackages - Create a GitHub Release
- Upload to PyPI (if
PYPI_API_TOKENsecret is set)
- Build
Release Candidate (RC)
- Bump version to RC format (e.g.,
0.2.0rc1) - Tag with RC pattern:
git commit -am "chore: bump version to 0.2.0rc1" git tag v0.2.0-rc1 git push --follow-tags
- GitHub Actions will:
- Build packages
- Create a GitHub Pre-Release
- Upload to TestPyPI (if
TEST_PYPI_API_TOKENsecret is set)
PyPI Tokens
Add tokens in GitHub repository settings:
- Settings → Secrets and variables → Actions → New repository secret
PYPI_API_TOKEN— For production releasesTEST_PYPI_API_TOKEN— For release candidates
❓ FAQ
Why do I need both tools?
- envdiff: Compare configurations and generate patches for synchronization
- envset: Quickly update a single key across multiple files
Can I use these tools with Docker?
Yes! Both tools work inside Docker containers. Mount your config files as volumes and run the commands.
How do I handle secrets?
Use --exclude to filter out secret keys from comparisons:
envdiff --source config.yml --target .env --exclude 'SECRET|PASSWORD|KEY'
Can I compare more than two files?
Currently, envdiff compares one source to one target. For multiple comparisons, run the command multiple times or use a script.
What Python versions are supported?
Python 3.8 and above.
📄 License
MIT License — see LICENSE file for details.
🤝 Contributing
Contributions are welcome! Please ensure:
- All tests pass (
pytest) - Code coverage remains at 100%
- Code follows style guidelines (
ruff check)
📚 Additional Resources
- Run
envdiff --helporenvset --helpfor full command-line options - Check
examples/directory for sample files - Review test files in
tests/for usage examples
Made with ❤️ for developers who care about configuration management
Metadata
Release files for envdiff-tool 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| envdiff_tool-0.1.2.tar.gz | 42.6 kB | Without provenance | Details for envdiff_tool-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| envdiff_tool-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for envdiff_tool-0.1.2-py3-none-any.whl |
Total release size: 68.1 kB
Release files / envdiff_tool-0.1.2.tar.gz
| Download URL | envdiff_tool-0.1.2.tar.gz |
|---|---|
| Size | 42.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3c3968930c581d58693c142950e1c3753ee5aef855b91420fd28334a554eba1e
|
|
BLAKE2b-256 checksum How to use checksums |
0c81de3a8bbddb07c370ce9de69404a3614025d3a567a2ff84c35b263be3c8fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / envdiff_tool-0.1.2-py3-none-any.whl
| Download URL | envdiff_tool-0.1.2-py3-none-any.whl |
|---|---|
| Size | 25.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
651dc89d9af8af6ddac8974a3503ac59c6ce2d72f4e4e4484684b877606b8287
|
|
BLAKE2b-256 checksum How to use checksums |
7640d95142a33141651f86e5cccc85290cb7731cc346b6ce8f25f196d0dd45f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for envdiff-tool 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.