restore

Restore environment files from the global store back into your repository.

Usage

envi restore

# Use the local store without checking GitHub
envi restore --no-pull

Description

The restore command reads your stored environment configuration and recreates all .env files in your repository with their original content and comments. When GitHub version control is enabled, it first runs git pull --ff-only in ~/.envi. If the pull fails, envi warns that the local data may be stale and continues restoring from it.

Use --no-pull to skip the GitHub check, such as in a script that manages synchronization separately.

What It Does

1. Updates the store - Fast-forwards a GitHub-backed ~/.envi clone unless --no-pull is set
2. Finds repository root - Locates your project root
3. Reads package name - Gets name from package.json or uses folder name
4. Loads stored config - Reads from ~/.envi/store/{package-name}.maml
5. Restores files - Recreates each .env file with preserved comments

File Handling

New Files

Files that don't exist are created automatically:

✔ Restored 3 file(s):
  ✓ .env.local
  ✓ apps/web/.env.production
  ✓ packages/api/.env

Unchanged Files

Files with identical content are skipped:

ℹ Skipped 2 unchanged file(s):
  - .env.test
  - services/api/.env.dev

Encrypted Stores

If the stored MAML was captured with at-rest encryption enabled, restore automatically decrypts each entry using envi.config.maml from the repository root:

$ envi restore
...
ℹ Decrypting env values with key from envi.config.maml
✔ Found 3 file(s) to restore

If the store contains encrypted entries but envi.config.maml is missing, restore fails with a clear error:

 ERROR  Stored data is encrypted but no encryption_key was found in 'envi.config.maml'.
ℹ Make sure envi.config.maml is present at the repository root and contains the original key (it should be committed to the source repo).

The same error appears if envi.config.maml exists but its encryption_key doesn't match the one used to capture (e.g., after a --force rotation). Re-capture from a checkout that has the original env files to recover.

Modified Files

When a file exists with different content, you'll be prompted:

⚠ File exists with different content: .env.local

? What would you like to do?
  ❯ No - skip this file
    Yes - overwrite this file
    Yes to all - overwrite all remaining files

Options:

• No (default) - Skip this file, keep existing version
• Yes - Overwrite this file with stored version
• Yes to all - Overwrite all remaining files without asking

Smart Comparison

Envi uses semantic comparison, not string comparison:

• Ignores formatting: Quotes, whitespace differences
• Ignores blank lines: Doesn't matter if you added/removed empty lines
• Compares content: Only checks actual keys, values, and comments

This means files with different formatting but same content are considered identical.

Examples

Successful Restore

$ envi restore
◐ Finding repository root...
ℹ Repository root: /Users/you/projects/myapp
ℹ Package name: @myorg/myapp
◐ Looking for stored configuration...
✔ Found stored configuration
✔ Found 5 file(s) to restore

✔ Restore complete!
✔ Restored 3 file(s):
  ✓ .env.local
  ✓ apps/web/.env.production
  ✓ packages/api/.env

ℹ Skipped 2 unchanged file(s):
  - .env.test
  - services/api/.env.dev

No Stored Configuration

$ envi restore
 ERROR  No stored configuration found for this repository.

ℹ Run 'envi capture' first to capture env files.

Interactive Overwrite

$ envi restore
...
⚠ File exists with different content: .env.local
? What would you like to do? Yes - overwrite this file

✔ Restored 1 file(s):
  ✓ .env.local

ℹ Skipped 1 file(s) (user declined):
  - .env.production

Use Cases

New Machine Setup

If you have GitHub integration enabled, first restore your envi store from GitHub (see envi global github restore), then restore your project's env files:

# Clone your project
git clone git@github.com:org/project.git
cd project

# If using GitHub integration, restore envi store first:
envi global github restore

# Restore env files
envi restore

Git Worktree

# Create new worktree
git worktree add ../project-feature feature-branch
cd ../project-feature

# Restore env files
envi restore

After Pulling Changes

If env file locations changed:

git pull
envi restore  # Update files to match stored config

Related Commands

• capture - Capture env files to storage
• create-key - Enable at-rest encryption for captured values
• global github restore - Restore entire envi store from GitHub