restore command restores your .env* files from backups created by the sync command. It features automatic backup discovery, validation, rollback capability, and comprehensive error handling.
Usage
Key Features
Auto-Discovery
Automatically finds and selects the most recent valid backup when no timestamp is provided
Backup Validation
Validates backup integrity and completeness before restoration
Rollback Protection
Creates pre-restore snapshots for automatic recovery if restoration fails
Cross-Platform
Works seamlessly on Windows, macOS, and Linux
Arguments
Specific backup timestamp to restore (format:
YYYYMMDD-HHMMSS)If omitted, the most recent valid backup will be automatically selected.Example:Options
Skip confirmation prompt and proceed with restoration immediatelyAliases:
-yExample:List all available backups without performing a restoreDisplays:
- Valid backups with timestamps and file lists
- Invalid backups with error messages
- Usage examples for restoration
Preserve original file permissions during restorationWhen enabled, files are restored with the same permissions they had when backed up.Example:
Preserve original file modification timestampsWhen enabled, restored files maintain their original modification times from the backup.Example:
Create a pre-restore snapshot for rollback capabilityAliases:
--rollbackIf the restore operation fails, the snapshot can be used to automatically rollback to the pre-restore state.Example:Force restore without checking for file changesAliases:
-fBypasses safety checks that normally warn about existing file modifications.Example:Show what would be restored without making any actual changesAliases:
--simulatePerfect for previewing the restore operation before committing to it.Example:Enable verbose logging for detailed operation informationAliases:
-VProvides detailed progress information, file-by-file status, and debugging information.Example:Display help information for the restore commandAliases:
-hExample:Examples
Restore most recent backup (automatic)
Restore most recent backup (automatic)
The simplest way to restore - automatically selects the most recent valid backup:Output:
Restore specific backup timestamp
Restore specific backup timestamp
Restore a specific backup by providing its timestamp:Output:
List available backups
List available backups
View all available backups without restoring:Output:
Restore with confirmation skip
Restore with confirmation skip
Skip the confirmation prompt using or with a specific timestamp:This is useful for:
--yes:- Automated scripts
- CI/CD pipelines
- Quick emergency restores
Dry-run to preview changes
Dry-run to preview changes
Preview what would be restored without making changes:Output:
Restore with rollback protection
Restore with rollback protection
Create a pre-restore snapshot for automatic recovery:If the restore fails, the snapshot will be automatically used to rollback:
Advanced restore with multiple options
Advanced restore with multiple options
Combine multiple options for maximum control:This will:
- Create a rollback snapshot before restoring
- Preserve original file permissions
- Preserve original file timestamps
- Show detailed logging throughout the process
Force restore (override warnings)
Force restore (override warnings)
Force restoration even if files have been modified:
Restore Process Flow
The restore command follows a comprehensive process:Backup Validation
Before restoration, env-twin validates each backup:- Structure Check: Verifies backup directory structure
- Timestamp Format: Validates timestamp format (
YYYYMMDD-HHMMSS) - File Existence: Confirms all backup files exist
- File Integrity: Checks files are readable and not corrupted
- Metadata Validation: Ensures backup metadata is complete
Invalid backups are excluded from automatic selection but are shown in
--list output with error details.Rollback Capability
When using--create-rollback, env-twin creates a snapshot before restoration:
- Pre-Restore Snapshot: Captures current state of all files
- Metadata Storage: Stores file permissions, timestamps, and content
- Automatic Recovery: If restore fails, automatically reverts to snapshot
- Manual Rollback: Snapshot can be manually restored if needed
- Maximum file size: 1MB per file
- Files larger than 1MB are skipped with a warning
- Snapshots are temporary and cleaned up after successful restore
Best Practices
Always preview with --dry-run first
Always preview with --dry-run first
Before restoring in production, preview the changes:
Use --create-rollback for safety
Use --create-rollback for safety
Enable rollback protection for critical environments:
List backups before restoring
List backups before restoring
Check available backups before restoration:
Preserve file metadata
Preserve file metadata
Keep original permissions and timestamps:
Related Commands
sync
Sync command that creates the backups
clean-backups
Manage and clean old backups
Troubleshooting
No backups found
No backups found
Problem: Command reports “No backups found in .env-twin/ directory”Solution: Run
env-twin sync first to create a backup:Invalid backup timestamp
Invalid backup timestamp
Problem: “Backup with timestamp ‘X’ not found or invalid”Solution: List available backups and use a valid timestamp:
Permission denied during restore
Permission denied during restore
Problem: Cannot write to .env filesSolution: Check file permissions and ownership:Or use
--force to override (not recommended):Restore fails mid-operation
Restore fails mid-operation
Problem: Restore fails partway throughSolution: If you used
--create-rollback, the rollback happens automatically. Otherwise, restore the previous backup: