Restoring Files from a Restic Backup with Pikkumies
Get a deleted file back from your restic backup with one plain sentence: Pikkumies finds the file in your latest snapshot, restores it into a fresh folder, moves it back without overwriting anything and reads it back to prove it. In the test run below that took one request, 2 minutes 16 seconds and 14,251 AI credits.
This page starts where Zero-Knowledge Backups with Pikkumies ends: a restic repository on a Pulsed Media Storage Box, made from your own Linux machine, with Pikkumies logged in to it. Setting that up, and what stays private, is on that page.
Recorded on Pulsed Media test accounts: a Linux account stands in for your machine (shown as you@laptop) and a second test account plays the Storage Box. The repository, the login and one backup of a small Documents folder (3 files) were set up beforehand, and the file was deleted just before the request. The clip leaves out the one-time setup of Pikkumies' agent runtime on its first start (3½ minutes) and shortens a 77-second wait.
Ask for the file back
Name the file and say where it should come from:
pikkumies "I deleted Documents/taxes/2026.txt by mistake. Get it back from my latest backup. Keep it short."

In the clip Pikkumies works through the steps of its restic instructions:
- It searches its notes, confirms the file is gone, asks the backup check which backup is newest (a restic snapshot from a few minutes earlier) and lists the snapshots.
showwith--files: the snapshot holdstaxes/2026.txt.restoreinto a new folder,~/restore-20261117, with--includeso only that file comes back. The file lands under its full original path inside the folder.mv -nback to~/Documents/taxes/2026.txt. The-nmeans it never writes over a file that is already there. Then it lists and prints the file.findshows no files left in the restore folder, andrmdirremoves the empty folders.rmdircannot delete a file.
The same steps by hand, with your own snapshot id and user name:
php ~/pikkumies/tools/backup/restic/restic.php list --limit 5 --human php ~/pikkumies/tools/backup/restic/restic.php show SNAPSHOT --files /home/USER/Documents/taxes php ~/pikkumies/tools/backup/restic/restic.php restore SNAPSHOT --target ~/restore-20261117 --include /home/USER/Documents/taxes/2026.txt mv -n ~/restore-20261117/home/USER/Documents/taxes/2026.txt ~/Documents/taxes/ cd ~ && rmdir -p restore-20261117/home/USER/Documents/taxes
Plain restic does the same with restic -r REPOSITORY restore latest --target ~/restore-20261117 --include /home/USER/Documents/taxes/2026.txt, asking for the passphrase.
Reading the answer
The answer in the clip is the receipt, and each line can be checked:
- The snapshot it came from and when it was taken, and what the backup check says about the backups.
- The restored file's path, size and content as read back.
- Checks: the file has its original permissions, and the temporary restore folder held nothing else and is removed.
Pikkumies restores only into a new or empty folder inside your home and refuses one that already has files in it, so a restore never mixes with your own files. A restore folder that still holds files after the move, for example when you restored a whole folder and took one file out, stays unless your request asks for it to go. In an earlier test run Pikkumies tried to remove its restore folder with rm -rf, which deletes files too; its safety check refused that because the request had not asked for it, and the answer listed the step as skipped.
The requests in the next sections were not recorded; what Pikkumies does with them follows its restic instructions.
An older version
Every backup is a separate snapshot, and restic keeps each one until it is removed. To get a file as it was on an earlier day, say which day: Pikkumies lists the snapshots with their times and can restore from any of them by its id.
pikkumies "Show my backups from last week and get Documents/taxes/2026.txt as it was on Monday."
Is the backup readable? Three levels of check
| Request | What runs | What it reads |
|---|---|---|
| "Check my backup." | check |
The repository's structure and index only: quick, little traffic |
| "Check a sample of the stored data." | check --read-data-subset 5% |
About one twentieth of the stored data |
| "Read the whole backup back." | check --read-data |
Every stored byte, which takes time and traffic for a large backup |
Pikkumies reads the stored data only when you ask for it. In the check's output, errors_found: true means restic found damage. finished: false means the check stopped early, for example on a lock, the network or the login, and says nothing about damage either way. A percentage needs restic 0.12 or newer; with an older restic ask for a fraction instead, such as 1/20.
Removing old snapshots
Removing snapshots deletes them for good, so it is two steps:
- Pikkumies shows which snapshots a keep rule would remove, for example
show --prune-plan --keep-daily 7 --keep-weekly 4, with a count called expect. - When your request asked for old snapshots to be removed, it runs
prunewith the same rule and that count. If the plan has changed in between, the count no longer matches and the prune is refused; Pikkumies shows the new plan instead of working around it.
pikkumies "Remove old backups. Keep one a day for a week and one a week for a month."
A request that only asks to see the plan gets the plan and nothing is deleted.
Locks and the cache
- repository is already locked: a restic run that was cut off can leave a stale lock.
statsshows locks in the repository, and Pikkumies runsrestic unlock, which clears only stale locks, when it sees one. - disk quota exceeded: restic keeps a cache in
~/.cache/restic. On an account with a disk quota the cache counts against it, andrestic cache --cleanupremoves old cache folders. Pikkumies runs it when the cache is the measured cause.
Troubleshooting
- no restic repository is set up for this tool: the login from Zero-Knowledge Backups with Pikkumies Step 3 has not been done on this machine.
- The restore refuses the target folder: it already has files in it. Use a new folder name.
- The file is not in the snapshot: the backup was made before the file existed, or the folder was not part of the backup. Ask Pikkumies to list the other snapshots.
See also
- Zero-Knowledge Backups with Pikkumies: setting up the repository, the login and the first backup
- Encrypted Backups from Your Seedbox with Pikkumies: borg backups from a seedbox account, with the same restore and prune steps
- Restic S3 Backup to Your Storage Box on PMSS: restic over the box's S3 endpoint, without Pikkumies
- 3-2-1 Backup Strategy: why one backup copy is not enough
- Storage Boxes: plans and protocols, and the AI credits each payment earns