Command builder
Borg backup and restore command generator
Backups you set up once and forget — until you need to restore. Pick what you're doing and copy the exact command. Restore is front and centre.
Composed repo: —. Using a non-default SSH key or port options? Set the SSH command below.
⚠ Lose the passphrase (and key) and the backup is gone forever — there is no recovery. With keyfile modes the key lives only on this machine, so export and store it offsite.
Borgmatic's list, prune and check only see archives matching this name (web-{now} → web-*): rename it later and older archives drop out.
Blank → list every archive in the repo. With a name → list the files inside that archive. (No :: = repo level; ::name = archive level — the distinction that trips everyone up.)
Extract: pull files straight back to disk. Best when you know the exact path.
Retention — how many to keep per period
The steps below preview the prune first, then run it and free the disk space.
Remote & unattended (SSH, passphrase)
Plain text: anyone who can read your borgmatic config, or your script and shell history with raw borg, can read the passphrase. Safer: a passphrase command, such as cat /root/.borg-passphrase on a file only root can read.
Warning: prune deletes whole backups. Every archive your keep rules don't cover is removed from the repository, and there's no undo. Run the preview first and read its list: each "Would prune" line is a backup that will be deleted. If several machines share this repository, limit prune to this machine's archives with "Scope to".
Prune safely, in this order
-
Check your config (/etc/borgmatic/config.yaml) has these lines
-
Preview: nothing is deleted
-
Prune for real
-
Free the disk space
The preview marks every archive "Keeping" or "Would prune". Prune only takes archives off the list; the disk space comes back when compact runs, which is the classic "I pruned but the disk is still full". Compact needs Borg 1.2 or later; older versions free the space during prune. In borgmatic mode, these commands need borgmatic 1.8 or later.
Restore — the part everyone forgets
- Extract vs Mount
- Extract pulls files back to disk — fastest when you know the exact path. Mount exposes the archive (or the whole repo) as a browsable folder via FUSE, so you can hunt for what you need in a file manager, copy it out, then
borg umount. - The extract gotcha
borg extracthas no output-directory flag — it always writes into your current directory. This builder generates themkdir -p … && cd …line so you don't dump a restore over your live files. (Borgmatic mode avoids this with--destination, after amkdir -p: that folder must already exist.)- Leading slash
- Paths inside an archive are stored relative —
home/joe/file, not/home/joe/file. The builder strips the leading slash for you.
Prune & compact
borg prune applies your --keep-* rules and removes old archives — but it only deletes references. Space is reclaimed only when you run borg compact afterwards. Always dry-run prune first, and use --glob-archives to scope it when several machines share one repo (otherwise prune compares unrelated archives).
Encryption & the passphrase
repokey stores the (encrypted) key inside the repo — the safe default for most people. keyfile keeps the key on the client only, so you must back it up offsite. Either way: a lost passphrase means permanently lost data — Borg has no recovery path. For cron, supply it via BORG_PASSCOMMAND (pulled from a secret store) rather than a plaintext BORG_PASSPHRASE.
Remote repositories (SSH)
A Borg repo can live on another server reached over SSH — the same commands work, you just point them at an ssh://user@host:port/path URL instead of a local path (a path without a leading slash is taken relative to the SSH login's home, written /./path). The remote server needs borg installed too. For unattended/cron runs, set BORG_RSH to choose the SSH key (e.g. ssh -i /root/.ssh/borg_key) and supply the passphrase via BORG_PASSCOMMAND — both under "Remote & unattended" above. In borgmatic they're config lines instead: ssh_command and encryption_passcommand. Tip: an append-only SSH key on the server lets a client add backups but not delete them (ransomware protection); pruning then has to be done later with a full-access key.
Version note
These commands target Borg 1.2 / 1.4 (current stable in 2026), which uses the repo::archive syntax. Borg 2.0 is still beta and changes that to -r REPO … archive — don't mix the two.
Sources & references
- BorgBackup documentationBorgBackup
- Borg quick startBorgBackup
- borg extract — restoring filesBorgBackup
- Borgmatic documentationBorgmatic