env-snapper

Security Note: It is strongly recommended to add .env-snapshots/ to your .gitignore to avoid accidentally committing sensitive environment history to your repository.

Automatically snapshots .env changes and lets you revert to previous environment variable states.

Features

• Snapshots .env file changes automatically
• Comprehensive metadata collection
• Configurable snapshot directories
• File-based snapshot storage
• Hook system for post-snapshot actions
• Error handling and validation
• Progress tracking
• TypeScript support
• Enhanced Security: Encryption for exported snapshots
• Tagging System: Organize snapshots with custom tags
• Enhanced Diff View: Compare snapshots with ignore options and sensitive variable highlighting
• Plugin System: Extend functionality through custom plugins
• Performance Caching: Improved performance with intelligent caching
• Analytics: Usage tracking and reporting
• Health Checks: Verify snapshot integrity

Installation

npm install -D env-snapper

Usage

# Create a snapshot
npx env-snapper snapshot

# List snapshots
npx env-snapper list

# Revert to a specific snapshot
npx env-snapper revert <snapshot-id>

Configuration

Create a env-snap.config.json file in your project root:

{
  "snapshotDir": "path/to/snapshots",
  "files": [
    ".env",
    ".env.local"
  ],
  "hooks": [
    {
      "type": "shell",
      "command": "echo Snapshot created: $SNAPSHOT_ID"
    }
  ],
  "encryption": {
    "enabled": true,
    "algorithm": "aes-256-cbc"
  }
}

License

MIT

• List, view, and revert to previous environment variable states
• CLI tool for easy usage
• Add descriptions to snapshots
• Auto-prune old snapshots to keep only the latest N
• Preview changes before restoring a snapshot

Usage

npm i env-snapper

# Initialize env-snap in your project
npx env-snap init

# Manually snapshot current .env
npx env-snap snapshot

# List all snapshots
npx env-snap list

# Revert to a previous snapshot
npx env-snap revert <snapshot-id>

# Show diff between snapshots or with current .env
npx env-snap diff <snapshot-id>            # Compare with previous snapshot
npx env-snap diff <snapshot-id> --current  # Compare with current .env

# Watch .env for changes and snapshot automatically
npx env-snap watch

# Add a description to a snapshot (after creation)
npx env-snap desc <snapshot-id> "Your description here"

# Example: create a snapshot with a description
npx env-snap snapshot --desc "Added Sentry config and removed Stripe keys"

# Prune old snapshots, keeping only the latest 5 (default)
npx env-snap prune

# Prune and keep only the latest N snapshots (e.g., 10)
npx env-snap prune 10

# Preview changes before restoring a snapshot
npx env-snap preview <snapshot-id>

# Tag a snapshot
npx env-snap tag <snapshot-id> "production"

# List snapshots with a specific tag
npx env-snap list --tag "production"

# Remove a tag from a snapshot
npx env-snap untag <snapshot-id> "production"

# Verify snapshot integrity
npx env-snap verify

# Clear the cache
npx env-snap cache-clear

# Show analytics report
npx env-snap analytics-report

Enhanced Features

Tagging System

Organize your snapshots with custom tags:

# Create a snapshot with tags
npx env-snap snapshot --tags "production,release-v1.2"

# Add tags to existing snapshot
npx env-snap tag <snapshot-id> "production"

# List snapshots with specific tag
npx env-snap list --tag "production"

# Remove tag from snapshot
npx env-snap untag <snapshot-id> "production"

Enhanced Diff View

Compare snapshots with more detailed information:

# Ignore specific variables in diff
npx env-snap diff <snapshot-id> --ignore "SECRET_KEY,DATABASE_URL"

# Sensitive variables are automatically highlighted
npx env-snap diff <snapshot-id>

Encryption for Exported Snapshots

Secure your exported snapshots with encryption:

# Export snapshots with encryption
npx env-snap export my-snapshots.zip --encrypt --password "mypassword"

# Import encrypted snapshots
npx env-snap import my-snapshots.zip --decrypt --password "mypassword"

Plugin System

Extend env-snapper functionality with custom plugins:

# Plugins are automatically loaded from the env-snap-plugins directory
# Execute plugin commands
npx env-snap plugin:<plugin-name>:<command-name>

How it works

• Snapshots are stored in .env-snapshots/ in your project directory (configurable).
• Each snapshot is named with a timestamp or unique ID.
• Descriptions can be added at creation (--desc) or later (desc command).
• list shows snapshot descriptions if present.
• revert prints the snapshot description if available.
• File watcher can automatically snapshot on changes (optional).
• All commands respect your config file if present.

Configuration

You can add an env-snap.config.json file to your project root to customize behavior:

{
  "snapshotDir": ".env-snapshots", // Where to store snapshots
  "files": [".env", ".env.local"],
  "encryption": {
    "enabled": false,
    "algorithm": "aes-256-cbc"
  }
}

If not specified, defaults are used. All commands (snapshot, revert, diff, preview, prune, watch, etc.) will respect these settings.

Export / Import Snapshots

You can export all snapshots to a zip file and import them into another project or machine:

• Export all snapshots:

  npx env-snap export my-snapshots.zip

• Import snapshots from a zip file:

  npx env-snap import my-snapshots.zip

• Export snapshots with encryption:

  npx env-snap export my-snapshots.zip --encrypt --password "mypassword"

• Import encrypted snapshots:

  npx env-snap import my-snapshots.zip --decrypt --password "mypassword"

This is useful for sharing environment history, moving between machines, or backing up your snapshot archive.

Git Integration

You can commit, push, pull, tag, and run hooks on your snapshot history directly from env-snap:

• **Commit all snapshot changes:**s

  npx env-snap git-commit -m "env-snap: update"

  (If no message is provided, a default message is used.)

• View git log for snapshots:

  npx env-snap git-log

• Push snapshots and tags to remote:

  npx env-snap push

• Pull snapshots and tags from remote:

  npx env-snap pull

Hooks & Notifications

env-snap supports running hooks and sending notifications after each snapshot. You can use:

• Shell hooks (run local commands)
• Webhooks (POST to any URL)
• Slack (send to a Slack channel)
• Discord (send to a Discord channel)
• Teams (send to a Microsoft Teams channel)

Add a hooks array to your env-snap.config.json:

"hooks": [
  {
    "type": "shell",
    "command": "echo 'Snapshot $SNAPSHOT_ID taken by $USER on $HOST' >> .env-snapshots/hook.log"
  },
  {
    "type": "webhook",
    "url": "https://example.com/webhook",
    "body": {
      "text": "Env snapshot $SNAPSHOT_ID taken by $USER on $HOST"
    }
  },
  {
    "type": "slack",
    "webhook": "https://hooks.slack.com/services/XXX/YYY/ZZZ",
    "message": "Env snapshot $SNAPSHOT_ID taken by $USER on $HOST"
  },
  {
    "type": "discord",
    "webhook": "https://discord.com/api/webhooks/XXX/YYY",
    "content": "Env snapshot $SNAPSHOT_ID taken by $USER on $HOST"
  },
  {
    "type": "teams",
    "webhook": "https://outlook.office.com/webhook/XXX/YYY/ZZZ",
    "text": "Env snapshot $SNAPSHOT_ID taken by $USER on $HOST"
  }
]

You can use $SNAPSHOT_ID, $USER, and $HOST in your messages for dynamic info.

Advanced Git Automation

You can enable automatic git actions in your env-snap.config.json:

{
  "autoGitCommit": true,        // Auto-commit after each snapshot
  "autoPush": true,             // Auto-push after each commit
  "branch": "main",            // Switch to this branch before commit
  "tag": true,                  // Tag each snapshot commit
  "commitHooks": [              // Run these shell commands after commit/push
    "echo 'Snapshot taken!' > .env-snapshots/hook.log"
  ]
}

Every snapshot will:

• Switch to the specified branch (if set)
• Commit changes in .env-snapshots
• Tag the commit (if enabled)
• Push to the remote (if enabled)
• Run any commit hooks (e.g., notifications, scripts)

This allows you to fully automate backup, sync, and audit of your environment history.

Author

• Alex G.

This is an open-source project. Contributions welcome!