env-snaps

Snapshot and restore project .env files. Simple, fast, and minimal.

Package name: snaps-back Command: env-snaps and snaps-back This package installs two CLI commands named env-snaps and snaps-back. Both run the same tool — use whichever name you prefer.

Why this exists

• When you work on a project, your .env file (secrets and configs) changes between dev, staging, prod, etc.
• Manually copying/renaming .env gets messy and error-prone.
• env-snaps saves snapshots of your .env to files like .env.dev.snap and lets you quickly load them back.

You are never forced to learn a complex system---these are just plain text files in your repo folder.

Install

Local (recommended):

npm install --save-dev snaps-back

This gives you npx env-snaps ... inside your project.

Global (optional):

npm install --global snaps-back

Then you can run env-snaps ... anywhere.

Snapshots (what & where)

• A snapshot is a plain file: .env.<name>.snap in your chosen directory.
• By default, snapshots live in your project root (same folder as .env).
• You can override the directory via:
  • global flag --dir <path>, or
  • environment variable ENV_SNAPS_DIR.

Examples:

.env.dev.snap
.env.staging.snap
.env.prod.snap

Commands & Flags

Global options

• -d, --dir <path>: Directory to read/write .env and snapshots
  (Tip: can also set ENV_SNAPS_DIR to avoid repeating the flag)

save <name>

Save the current .env to .env.<name>.snap.

Options: - -f, --force: Overwrite the snapshot if it already exists.

Example (works with either command)

npx env-snaps save dev

or

npx snaps-back save dev

More examples:

# Save current .env as .env.dev.snap
npx env-snaps save dev

# Overwrite if exists
npx env-snaps save dev --force

load <name>

Load .env.<name>.snap into .env.

Options: - --backup: If a .env exists, first back it up to .env.backup.

Example:

# Load .env.dev.snap into .env
npx env-snaps load dev

# Backup existing .env -> .env.backup before loading
npx env-snaps load dev --backup

list

List all available .env.*.snap files.

Example:

npx env-snaps list

diff <name1> <name2>

Show a line-by-line diff between two snapshots.

Options: - --color (default) / --no-color

Example:

# Compare dev vs staging
npx env-snaps diff dev staging

# Force no color (useful for CI or logs)
npx env-snaps diff dev staging --no-color

Windows notes

• Works fine in PowerShell and CMD.
• If you pass numbers to any flags in the future, prefer parseInt(value, 10) in your own scripts to avoid octal parsing surprises.
  (This CLI doesn't parse numbers itself, but it's good practice.)

Minimal dependencies

• commander (argument parsing)
• diff (human-readable diffs)

Examples

# Save snapshots for multiple environments
npx env-snaps save dev
npx env-snaps save staging
npx env-snaps save prod

# Switch to dev quickly (backup current .env first)
npx env-snaps load dev --backup

# List what you have
npx env-snaps list

# See what changed between dev and staging
npx env-snaps diff dev staging

FAQ

Where are the files stored?
Right alongside your .env by default (or in the folder you pass via --dir / ENV_SNAPS_DIR).

Is it safe to commit snapshots?
Treat them like your .env --- if they contain secrets, do not commit them. Use .gitignore if needed.

Does the tool merge .env files?
No. It's intentionally minimal: it saves, loads, lists, and diffs.