Skip to content

Restic Restore Runbook

Disaster recovery procedure for restoring files from Cloudflare R2 backups using restic.

Prerequisites

  • restic installed — verify with restic version
  • Infisical CLI installed and authenticated (infisical login)
  • R2 credentials in Infisical (dev env): RESTIC_R2_ACCESS_KEY, RESTIC_R2_SECRET_KEY, RESTIC_PASSWORD
  • rclone installed and configured with r2 remote (restic uses rclone backend, not S3 direct)

Environment Setup (Bash / Git Bash)

The backup uses rclone as the restic backend — rclone handles R2 auth via ~/.config/rclone/rclone.conf. Only RESTIC_PASSWORD comes from Infisical.

Load the password and set the repository in one step:

cd /c/Users/accou/repos/liflode-scripts

# Get RESTIC_PASSWORD from Infisical and set env vars
RESTIC_PASSWORD=$(infisical run --env=dev -- bash -c 'echo $RESTIC_PASSWORD' 2>/dev/null | grep -v INF)
export RESTIC_PASSWORD
export RESTIC_REPOSITORY="rclone:r2:liflode-laptop-backups"

Then run all restic commands in the same shell session.

Repository format: rclone:r2:liflode-laptop-backups (NOT an S3 URL - rclone handles auth)

Note: infisical run --env=dev -- restic snapshots does NOT work because RESTIC_REPOSITORY is not stored in Infisical - it must be set manually as above.

List Available Snapshots

restic snapshots

Expected output — a table of snapshots:

ID        Time                 Host        Tags    Paths
------------------------------------------------------------
562d0e93  2026-04-27 21:15:27  R_Lenovo            C:\Users\accou

Use the snapshot ID (e.g. 562d0e93) or latest in restore commands below.

Restore a Single File

restic restore latest --target C:\temp\restore-temp --include "path/to/file.ext"

Example - restore a specific skills file:

restic restore latest --target C:\temp\restore-temp --include "Users/accou/.claude/skills/linear/SKILL.md"

The file will appear at C:\temp\restore-temp\C\Users\accou\.claude\skills\linear\SKILL.md.

Note on Windows paths: Restic restores the full absolute path under the target. A backup of C:\Users\accou\... restores to <target>\C\Users\accou\....

Expected warning on Windows: You will see ignoring error: failed to restore timestamp of "...\C\Users": Access is denied. This is a benign Windows permission issue on high-level directories. The file content is fully restored despite this warning. Verify via checksum.

Restore Full Backup

Always dry-run first to verify scope:

restic restore latest --target C:\temp\full-restore --dry-run

Then run without --dry-run to restore:

restic restore latest --target C:\temp\full-restore

After restore, copy from C:\temp\full-restore\C\Users\accou\ to the desired destination.

Warning: Never restore directly to C:\Users\accou\ - this would overwrite live files. Always restore to a temp directory, then selectively copy what you need. Confirm the snapshot date with restic snapshots before proceeding.

Validation Steps

After restoring, verify the restore succeeded:

  1. File exists at target path (bash): 

    ls /c/temp/restore-temp/C/Users/accou/.claude/skills/linear/CHANGELOG.md

  2. Checksum matches original (most reliable verification): 

    sha256sum /c/Users/accou/.claude/skills/linear/CHANGELOG.md
sha256sum /c/temp/restore-temp/C/Users/accou/.claude/skills/linear/CHANGELOG.md
# Hashes must be identical

  3. For Claude config - verify directory structure is intact: 

    find /c/temp/restore-temp -type f | wc -l
# Compare against expected file count

Post-Restore: Claude Config Files

If restoring Claude config (.claude/ directory), copy files back selectively:

# Restore skills
Copy-Item -Recurse "C:\temp\restore-temp\C\Users\accou\.claude\skills\" "C:\Users\accou\.claude\skills\"

# Restore agents
Copy-Item -Recurse "C:\temp\restore-temp\C\Users\accou\.claude\agents\" "C:\Users\accou\.claude\agents\"

# Restore projects (memory files)
Copy-Item -Recurse "C:\temp\restore-temp\C\Users\accou\.claude\projects\" "C:\Users\accou\.claude\projects\" -Force

After restoring, restart Claude Code to pick up any changed config.

Cleanup After Test Restore

Restic on Windows restores with restricted permissions on high-level directories. To delete the temp restore directory, use an elevated PowerShell session:

# Run as Administrator:
Remove-Item -Recurse -Force "C:\temp\restic-test-restore"

Or via the GUI: right-click the folder > Properties > Security > take ownership, then delete.

Troubleshooting

Symptom Fix
Connection error / timeout Verify rclone r2 remote is configured: rclone listremotes should show r2:. Check ~/.config/rclone/rclone.conf for R2 credentials.
Signature mismatch / auth error Do NOT use S3 URL with AWS_ACCESS_KEY_ID - use rclone backend only. Run rclone ls r2:liflode-laptop-backups to test rclone auth separately.
Wrong password error Verify RESTIC_PASSWORD matches the password used during restic init. Check Infisical dev env: infisical run --env=dev -- bash -c 'echo $RESTIC_PASSWORD'.
Snapshot not found / latest fails Run restic snapshots to list available IDs. Use a specific ID (e.g. restic restore 562d0e93) instead of latest.
Repository locked Run restic unlock to remove a stale lock left by an interrupted backup.
Corrupted snapshot Run restic check to verify repository integrity. Run restic rebuild-index if index is damaged.
infisical: command not found Install Infisical CLI: winget install Infisical.Infisical then run infisical login.
failed to restore timestamp ... Access is denied Benign Windows error on parent directories. File content is restored correctly. Verify via checksum.
Cannot delete restore temp dir Run PowerShell as Administrator to remove, or take ownership via Explorer > Properties > Security.

Test This Runbook

See IT-1904 for the end-to-end restore test procedure.