CLI Reference

SaveVault ships a full command-line interface alongside the desktop app. Anything the GUI does, you can script. The CLI and GUI share the same config.toml, state database, and backup folder, so you can mix them freely — a backup made from a terminal shows up on the Dashboard, and a game you toggle in the GUI is respected by the CLI.

The binaries

Every install includes three command-line executables next to the desktop app:

Binary	Purpose
savevault-cli	The full CLI documented on this page. Console program: prints output, accepts prompts.
savevault-wrap	The silent launch wrapper for Steam launch options, Heroic, Lutris, and Playnite. Same flags as savevault-cli wrap, but never opens a console window.
savevault-scheduled	The headless runner your OS scheduler fires for scheduled backups. You don’t run it by hand; savevault-cli schedule enable registers it.

On Windows the binaries end in .exe. They live in SaveVault’s install folder (for the Steam edition, inside steamapps/common/SaveVault; on Linux Steam installs keep them under x86_64/usr/bin (desktop Linux, Steam Deck, Steam Machine) or aarch64/usr/bin (Steam Frame) in that folder). Add that folder to your PATH, or call them with a full path.

All three append to one shared, rotating log so you can always answer “did it run last night?” from a single file — see Logs.

Global flags

These work with every command and are accepted either before or after the command name:

Flag	Effect
--json	Emit JSON instead of human-readable text (see JSON output for which commands support it).
--quiet	Suppress non-error output.
--verbose	Lift manifest/scanner debug tracing up to the console. Pair it with diagnose for bug reports.
--help / -h	Help for the CLI, any command, or any subcommand: savevault-cli restore --help.
--version / -V	Print the SaveVault version.

savevault-cli --json scan
savevault-cli --verbose diagnose "Elden Ring"
savevault-cli backups --help

Command index

Command	What it does
scan	Detect installed games and persist the scan cache.
list	List games in the database or detected on this machine.
backup	Back up detected games (or preview with --dry-run).
backup-preview	Show exactly what the next backup of one game would collect.
restore	Restore an archive, with dry-run, per-file selection, and path remapping.
restore-batch	Restore every archive in a folder (new-machine flow).
list-files	List an archive’s restorable inventory without extracting.
explain	Show where every root in an archive would restore to, plus its README.
backups	List and manage the backup library: pin, unpin, label, delete.
prune	Reconcile the state database with the backup folder.
verify	Deep-verify one archive, or all of them, against BLAKE3 checksums.
exclusions	Backup exclusions: path globs, registry ignores, the recommended preset.
restore-excludes	Persistent per-game globs applied to every restore.
redirects	Persistent path-prefix rewrites for backup and restore.
add / remove	Add or remove a custom game.
detection	Sticky detection from archived roots when the database drops a game.
manifest	Game database source and updates (update-manifest is the legacy alias).
config	Read or write any config key: list, get, set, unset.
settings	Export and import portable settings bundles.
roots	Install roots: list, discover, rescan.
schedule / schedule-run	OS-level scheduled backups and one-off passes.
live	Live Protection: start, snapshots, pins, per-game monitor list.
cloud	Cloud backup (rclone): status, sync, install, reset.
notifications	Fire test OS notifications.
diagnose	One-paste support report for a single game.
wrap	Run a game with SaveVault protection around it.

Scanning and listing

scan

Match your system against the PCGamingWiki / Ludusavi database plus your custom games, then persist the scan cache and the “new since last time” baseline — exactly what the GUI’s Dashboard does on launch.

Flag	Effect
--new-only	Only list games flagged as new since the last scan or acknowledge. Can’t be combined with --acknowledge-new.
--acknowledge-new	Dismiss the “new” labels using the on-disk cache, without scanning. Requires a current cache (run scan first). Can’t be combined with --new-only.

# Full scan
savevault-cli scan

# Machine-readable for scripting
savevault-cli --json scan

# What's new since I last looked?
savevault-cli scan --new-only

# Clear the "new" labels without walking the manifest again
savevault-cli scan --acknowledge-new

Games detected only through archived-root fallback show an [archived] marker. If nothing is detected, fetch the database with manifest update or add a custom game.

list

Flag	Effect
(none)	Every game name in the database.
--installed	Only games detected on this machine (runs a scan).

savevault-cli list
savevault-cli list --installed
savevault-cli --json list --installed

Backing up

backup

Back up every detected game, or just the ones you name. Archives are self-describing (see the archive format) and land in your backup folder under <Game>_<timestamp>_<device-tag>.<ext>.

Flag	Effect
--games <name>	Back up only this game. Repeat the flag for several. Matched case-insensitively against detected game names.
--format <zip|targz|tarzst>	Archive format for this run. Overrides default_format.
--output <dir>	Write archives here instead of backup_dir.
--compression <1-9>	Compression speed/ratio, 1 = fastest, 9 = smallest. Overrides backup_compression_speed (default 6). An out-of-range value is clamped silently to 1–9, whereas config set backup_compression_speed rejects it.
--dry-run	Print what each selected game would collect and where the archive would go. Writes nothing: no archive, no database rows, no cache.

# Everything detected
savevault-cli backup

# Specific titles
savevault-cli backup --games "Dark Souls III" --games "Elden Ring"

# Fastest possible zstd archive to an external drive
savevault-cli backup --games "Baldur's Gate 3" --format tarzst --compression 1 --output E:/SaveBackups

# Preview the plan for every game at once — nothing touches the disk
savevault-cli backup --dry-run
savevault-cli backup --games "Elden Ring" --dry-run

Backups respect your exclusions and retention.

backup-preview

Read-only preview of what the next backup of one game would collect. Currently excluded files are still listed, with the pattern that excludes them in the excluded-by column, so nothing goes invisibly missing. This is the CLI twin of the Backup page’s Files tree.

savevault-cli backup-preview "Elden Ring"
savevault-cli --json backup-preview "Elden Ring"

The game must be currently detected (case-insensitive match). For every game at once, use backup --dry-run.

Restoring

restore

Restore an archive, or a directory the archive was already extracted into. Portable placeholders resolve against the machine you run this on, so a same-OS restore just works, even under a different user name.

Before writing anything, restore archives the current on-disk state of everything it would overwrite as a normal labeled backup in your library. Every restore is undoable by restoring that safety archive.

Flag	Effect
<archive>	Path to the archive, or to an extracted directory.
--games <name>	Only restore this game (repeatable). Archives are single-game, so this mostly matters for extracted directories.
--dry-run	Show what would be restored. Writes nothing.
--include <saves|configs|both>	What to bring back. Defaults to the configured restore.include_mode, which is saves out of the box.
--include-registry / --no-include-registry	Whether to import Windows registry keys and Proton hives from the archive. On by default.
--file <archive-path>	Restore only this file, by its in-archive path (repeatable). Get the exact strings from list-files. Registry entries aren’t selectable this way.
--exclude <glob>	Skip destination paths matching this glob (repeatable). Same pattern dialect as exclusions add. Composes with persisted restore-excludes.
--remap-root <id>=<path>	Send one root somewhere else for this run (repeatable). The path is a folder, or for a single-file root the full destination file path including its name. Root ids, which roots are single files, and starting-point folders on this machine come from explain.
--cross-platform	Opt in to restoring across Windows / Linux / macOS by resolving paths through the database’s per-platform templates.
--redirect-wine / --no-redirect-wine	Materialize Windows-layout saves into a Wine/Proton prefix, or force that off for this run.
--no-redirects	Ignore persistent path redirects for this run.
--redirects <file>	Load redirects from a different TOML file.
--no-pre-restore-backup	Skip the safety backup.

# Same machine, same OS
savevault-cli restore "D:/SaveVault/Elden Ring_2026-09-01_22.15.03.zip"

# Always preview first when unsure
savevault-cli restore backup.zip --dry-run

# Saves only (default), configs only, or both
savevault-cli restore backup.zip --include saves
savevault-cli restore backup.zip --include both

# Bring back a single file
savevault-cli list-files backup.zip
savevault-cli restore backup.zip --file "data/saves/appData/EldenRing/ER0000.sl2"

# Everything except screenshots
savevault-cli restore backup.zip --exclude "screenshots/" --exclude "*.png"

# Skip the registry part of a Windows archive
savevault-cli restore backup.zip --no-include-registry

# Send root 0 to a different install folder
savevault-cli restore backup.zip --remap-root 0=D:/Games/Skyrim

# Windows archive onto a Linux machine
savevault-cli restore backup.zip --cross-platform

# Into a Proton prefix on Steam Deck
savevault-cli restore backup.zip --redirect-wine

# Ignore persistent redirects just this once
savevault-cli restore backup.zip --no-redirects

restore exits non-zero if the archive isn’t found, if any restore action fails, or if nothing at all was restored while entries were skipped for a real reason (an unresolved root, a game that isn’t installed). Skips you asked for, such as --include filters, don’t count. A --dry-run writes nothing and exits 0 unless the archive can’t be read.

Restore verifies each file’s BLAKE3 hash before writing it and restores modification times. When a game uses launcher cloud sync (Steam, GOG, Epic…), SaveVault warns you first, because the launcher may overwrite the restored save on its next sync. When several devices share the backup folder and the archive doesn’t include another device’s newer progress, restore prints that warning too.

restore-batch

Restore every archive in a directory with the same options. The new-machine flow: drop your archives in a folder, set up any redirects, run this once.

Accepts --dry-run, --include, --include-registry / --no-include-registry, --cross-platform, --no-redirects, --redirects <file>, --redirect-wine / --no-redirect-wine, --no-pre-restore-backup, and --exclude <glob> (applied to every archive). There is no per-file selection in batch mode; persisted restore-excludes still apply.

savevault-cli restore-batch D:/SaveVault/ --dry-run
savevault-cli restore-batch D:/SaveVault/
savevault-cli restore-batch ~/backups --cross-platform --include both

On a brand-new machine with no existing saves, the safety backup is skipped automatically, so --no-pre-restore-backup is rarely needed.

list-files

List an archive’s restorable inventory — files and registry entries — without extracting anything. The path column is exactly what restore --file expects.

savevault-cli list-files backup.zip
savevault-cli --json list-files backup.zip

explain

Show the planned destination for every root in an archive, plus the embedded README.txt. Read-only. Use it to learn root ids for --remap-root and to confirm a plan before restoring on a new machine or OS. It also lists remap starting points that exist on this machine — home, Documents, the OS save folders, each Steam library, and for a known Steam game its install folder, Proton prefix, and Steam Android container — the same chips the Restore page offers under each remap field.

Flag	Effect
--cross-platform	Plan a cross-platform restore.
--redirect-wine / --no-redirect-wine	Plan with or without Wine/Proton materialization.
--no-redirects	Ignore persistent redirects when planning.
--redirects <file>	Plan with a different redirects file.
--no-readme	Print only the plan.

savevault-cli explain backup.zip
savevault-cli explain backup.zip --no-readme
savevault-cli explain backup.zip --cross-platform --redirect-wine

The backup library

backups

List and manage stored archives. Every invocation first reconciles the state database with the backup folder — records for archives you deleted by hand are purged, and archives dropped into the folder (including ones made by other tools that follow the archive format) are adopted. This is the CLI mirror of the GUI’s Restore page.

Subcommand	Effect
(none) / --game <name>	List the library, optionally for one game. Each row names the device that made the backup.
--device <name|id-prefix|this>	Only backups made on one device: its name (case-insensitive), the start of its id, or this for this machine. Listing only.
pin <archive> [--label <text>]	Pin so retention never deletes it, optionally setting the label at the same time.
unpin <archive>	Unpin. The label is kept.
label <archive> <text>	Set the label shown next to the backup.
label <archive> --clear	Remove the label.
delete <archive> [--force]	Delete from disk and the library. Refuses pinned backups unless --force.

For pin, unpin, label, and delete, the archive path must be one the library tracks, meaning it sits inside a backup directory SaveVault knows about. Relative paths are resolved against the current directory, and archives dropped into the folder are adopted just before the lookup. Any other path fails with No backup record for …; run backups to list what’s tracked.

savevault-cli backups
savevault-cli backups --game "Elden Ring"
savevault-cli backups --device this
savevault-cli backups --device "Steam Deck OLED"
savevault-cli --json backups

savevault-cli backups pin "D:/SaveVault/Elden Ring_2026-09-01_22.15.03.zip" --label "before NG+"
savevault-cli backups label "D:/SaveVault/Elden Ring_2026-09-01_22.15.03.zip" "Malenia down"
savevault-cli backups label "D:/SaveVault/Elden Ring_2026-09-01_22.15.03.zip" --clear
savevault-cli backups unpin "D:/SaveVault/Elden Ring_2026-09-01_22.15.03.zip"
savevault-cli backups delete "D:/SaveVault/Elden Ring_2026-09-01_22.15.03.zip"
savevault-cli backups delete "D:/SaveVault/Elden Ring_2026-09-01_22.15.03.zip" --force

prune

The same reconciliation backups performs, without printing the listing. Handy after you’ve tidied the backup folder by hand. It prints a short summary of what it removed or adopted, or says the library is already in sync. With --json it prints the full reconciliation report instead.

savevault-cli prune
savevault-cli --json prune

verify

Deep-verify an archive: the whole-file hash against the one recorded at backup time (when the library knows it), plus every entry against the per-file hashes in the manifest.

Flag	Effect
<archive>	Verify this archive.
--all	Verify every archive in the backup directory.

Run with neither an archive nor --all, verify prints a hint and exits 0, having checked nothing. If any archive fails, it exits non-zero.

savevault-cli verify backup.zip
savevault-cli verify --all
savevault-cli --json verify --all

Retention also refuses to purge old backups while the newest surviving archive fails verification, so a corrupted latest backup never causes the good ones to be deleted.

Exclusions

exclusions

Manage what backups leave out: path globs and Windows registry-key ignores, applied wherever backups are collected — manual, scheduled, wrap, and live snapshots. Matching is case-insensitive.

Pattern	Matches
*.log (no /)	A file name, or any single path component, anywhere.
shadercache/ (trailing /)	Any directory with that name, anywhere.
Saves/Autosave*/ or **/thumbs/*.png (contains /)	Relative to each save location. ** crosses directories.

Registry ignores use subtree semantics: an entry ignores itself and everything under it.

Subcommand	Effect
(none) / list [--game <name>]	Show the recommended-preset state, global patterns, global registry ignores, and per-game sections.
add <pattern> [--game <name>] [--registry]	Add a global or per-game path glob, or a registry ignore.
remove <pattern> [--game <name>] [--registry]	Remove one (case-insensitive exact match).
recommended [--enable|--disable]	Show or toggle the built-in preset.

savevault-cli exclusions
savevault-cli exclusions list --game "Elden Ring"

# Global path globs
savevault-cli exclusions add "*.log"
savevault-cli exclusions add "crash_reports/"

# Per-game
savevault-cli exclusions add "shadercache/" --game "Elden Ring"
savevault-cli exclusions add "Screenshots/**" --game "Cyberpunk 2077"

# Registry ignores (Windows and Proton hives)
savevault-cli exclusions add "HKCU\Software\Foo\Telemetry" --registry
savevault-cli exclusions add "HKCU\Software\Bar" --registry --game "Bar Game"

savevault-cli exclusions remove "*.log"

# The recommended preset: common log / cache / crash-dump noise
savevault-cli exclusions recommended
savevault-cli exclusions recommended --enable
savevault-cli exclusions recommended --disable

The recommended preset covers *.log, logs/, *.tmp, *.dmp, *.mdmp, *.crash, cache/, caches/, shadercache/, crashes/, crash_reports/, Thumbs.db, and .DS_Store. See the exclusions guide for how the GUI’s per-file checkboxes map onto these patterns.

restore-excludes

Persistent per-game globs applied to every restore of that game, single or batch. Same pattern dialect as exclusions, matched relative to the restored root. Unlike backup exclusions there is no global list — restore excludes are always scoped to one game.

Subcommand	Effect
(none) / list [--game <name>]	Show configured restore excludes.
add <pattern> --game <name>	Add a glob for that game.
remove <pattern> --game <name>	Remove it.

savevault-cli restore-excludes
savevault-cli restore-excludes list --game "Skyrim"
savevault-cli restore-excludes add "*.ini" --game "Skyrim"
savevault-cli restore-excludes add "SKSE/" --game "Skyrim"
savevault-cli restore-excludes remove "*.ini" --game "Skyrim"

These apply regardless of --exclude; the two compose.

Path redirects

redirects

Persistent path-prefix rewrites applied during backup, restore, or both. Use them when a library moved drives, or when a new machine lays things out differently. Stored in path-redirects.toml next to your config.

Subcommand	Effect
show	Print the current rules (or a hint if the file is absent). With --json and at least one rule, prints the rules as JSON; with no rules it still prints the text hint.
add <backup|restore|bidirectional> <source> <target>	Add a rule. restore rewrites on the way back in, backup on the way out, bidirectional both.
remove <index>	Remove the rule at that zero-based index from show.
clear	Delete the redirects file.
path	Print where the redirects file lives.
export [-o <file>]	Write the rules to a TOML file.
import <file> [--dry-run]	Replace all rules from a TOML file.

# Old drive letter → new drive letter, on restore only
savevault-cli redirects add restore C:/OldSaves D:/NewSaves

# Two-way mapping applied on backup and restore
savevault-cli redirects add bidirectional D:/Games C:/Canonical/Games

savevault-cli redirects show
savevault-cli redirects remove 0
savevault-cli redirects path
savevault-cli redirects clear

# Move rules between machines
savevault-cli redirects export -o savevault-redirects.toml
savevault-cli redirects import savevault-redirects.toml --dry-run
savevault-cli redirects import savevault-redirects.toml

For a one-off override of a single root, use restore --remap-root instead. The Backup and Restore pages in the GUI show a banner when a redirect applies, with a per-run toggle to ignore it, which matches --no-redirects.

Custom games

add

Add a user-defined game. Only that entry’s scan cache is patched, so this is instant even with a large library. Every path flag accepts a folder (all files, recursively), a single file, or an absolute glob, and can be repeated. At least one of --path, --config-path, --reg, or --reg-config is required.

Flag	Effect
<name>	The game name.
--path <p>	A save location (repeatable).
--config-path <p>	A config location (repeatable). Restored only with --include configs or both.
--reg <key>	A Windows registry key to back up as save data (repeatable). Also used inside Proton prefixes.
--reg-config <key>	A registry key to back up as config data (repeatable).

# A whole folder
savevault-cli add "My Indie Game" --path "C:\Users\Me\Saves\MyIndieGame"

# Only certain files, by glob — repeat --path per pattern
savevault-cli add "My Indie Game" --path "C:\Users\Me\Saves\MyIndieGame\*.sav" --path "C:\Users\Me\Saves\MyIndieGame\*.cfg"

# Saves and configs kept separate, plus a registry key
savevault-cli add "Old Shareware" --path "D:\Games\Shareware\SAVES" --config-path "D:\Games\Shareware\game.ini" --reg "HKCU\Software\Shareware Inc\Game"

# Linux
savevault-cli add "My Indie Game" --path "<home>/.local/share/MyIndieGame/saves"

remove

savevault-cli remove "My Indie Game"

Custom games can also be added and edited from the Backup page (+ Add Game) and imported or exported under Settings → General → Custom Games in the GUI, and travel between machines in a settings bundle with --include-custom-games. Before adding one for a public game, consider fixing it on PCGamingWiki so everyone benefits.

Detection

detection

Sticky detection from archived roots. When the database stops listing a game (an upstream change drops its save template, say) but that game’s most recent backup still has working save locations on disk, scan keeps detecting it from those archived locations instead of letting it silently fall out of Live Protection and scheduled backups. The database always wins the moment it lists the game again.

Subcommand	Effect
(none) / list	Show the fallback state and the opt-out list (reports config only, no scan).
optout <game>	Manifest-only detection for this game.
optin <game>	Remove the game from the opt-out list.
archived-fallback [--enable|--disable]	Show or toggle the fallback globally.

savevault-cli detection
savevault-cli detection optout "RV There Yet?"
savevault-cli detection optin "RV There Yet?"
savevault-cli detection archived-fallback
savevault-cli detection archived-fallback --disable
savevault-cli detection archived-fallback --enable

Run scan or list --installed to see live [archived] markers on games currently detected this way.

Game database

manifest

The game database is the Ludusavi manifest generated from PCGamingWiki. Its source is a URL or a local file, and it’s fetched on demand or (in the GUI) on launch.

Subcommand	Effect
(none) / source	Show the configured source, the built-in default URL, when it was last updated, and whether manifest.yaml exists.
source <url-or-path>	Persist a custom source: an http(s):// URL or a local file.
source --clear	Back to the built-in default.
update	Fetch or read the database from the configured (or default) source.
update --source <url-or-path>	One-shot override. Not saved.

savevault-cli manifest
savevault-cli manifest update

# Air-gapped machine, or a hand-curated database
savevault-cli manifest source "D:\GameData\manifest.yaml"
savevault-cli manifest source "https://example.com/manifest.yaml"
savevault-cli manifest source --clear

# Try a file once without changing the setting
savevault-cli manifest update --source "D:\GameData\manifest.yaml"

savevault-cli update-manifest is a deprecated alias for the bare manifest update, kept for existing scripts. Switching sources always forces a fresh fetch; a stored HTTP ETag is only reused when the source hasn’t changed.

Configuration

config

Every GUI-settable option is reachable here. With no subcommand and no flags, config prints the current settings.

Subcommand	Effect
list	Every key with its current value, one key = value per line. Keys owned by a dedicated command are marked (dedicated: …); machine-managed ones (internal: …).
get <dotted.key>	Print one value. Works for every key, including dedicated and internal ones.
set <dotted.key> <value>	Set one value. Parsed and range/enum-validated for the field’s real type before saving, so an invalid value can never land in config.toml. Prints key: old -> new.
unset <dotted.key>	Clear an optional field back to unset. Required fields reject this.

Value syntax for set:

• Booleans: true / false.
• Integers: a plain number, range-checked (backup_compression_speed is 1–9).
• Enums: their lowercase name (zip, targz, tarzst; daily, weekly, monthly, interval; …). An invalid value’s error lists the valid ones.
• Paths and strings: taken verbatim.
• Optional fields: an empty string clears the value, same as unset.

savevault-cli config list
savevault-cli --json config list

savevault-cli config get backup_dir
savevault-cli config get live.hotkey

savevault-cli config set backup_dir "D:/SaveVault"
savevault-cli config set default_format tarzst
savevault-cli config set backup_compression_speed 9
savevault-cli config set retention.default_max_backups 8
savevault-cli config set schedule.time 22:30
savevault-cli config set restore.include_mode both
savevault-cli config set live.hotkey "Ctrl+Alt+S"
savevault-cli config set live.controller_hotkey "Select+RB"
savevault-cli config set cloud_backup.sync_after_backup true
savevault-cli config set notifications.scheduled_run_mode always
savevault-cli config set locale de
savevault-cli config set device.name "Living room PC"

savevault-cli config unset schedule.output_dir
savevault-cli config unset live.controller_hotkey       # disables the chord
savevault-cli config unset scan.parallelism             # back to "all CPUs"

Keys owned by a dedicated command are rejected by set/unset with a pointer to the right place instead of silently doing nothing:

savevault-cli config set exclusions.global "*.log"   # → use `exclusions add`
savevault-cli config set schedule.enabled true       # → use `schedule enable`
savevault-cli config set onboarding_completed false  # → internal, not settable

The full key catalog, with defaults and which command owns each dedicated key, is in the configuration reference.

Legacy flags

The original narrow flag surface still works for existing scripts. Prefer config set.

Flag	Same as
--backup-dir <dir>	config set backup_dir <dir>
--default-format <fmt>	config set default_format <fmt>
--retention <n>	config set retention.default_max_backups <n>
--retention-game "Game:count"	Per-game retention. No dotted-key equivalent, since retention.per_game_overrides is a map.
--theme <system|dark|light>	config set theme <value>

savevault-cli config --backup-dir "D:/SaveVault" --default-format zip
savevault-cli config --retention 6 --retention-game "Elden Ring:20"

Settings backup

settings

Export portable preferences to a TOML bundle and import them on another machine: schedule (including on/off), Live Protection options, notifications, manual install roots, cloud-sync preferences, and theme selection — optionally plus custom games and path redirects. Machine-local state is never exported: backup_dir, snapshot and scheduled output folders, live on/off, cloud on/off, cloud sign-in, and rclone paths.

Subcommand	Effect
export [-o <file>] [--include-custom-games] [--include-redirects]	Write a bundle.
preview <file>	Show what a bundle contains. Alias for import --dry-run.
custom-games-plan <file> [-o <plan>]	Write an editable TOML plan deciding Add / Replace / Skip per custom game.
import <file> [flags]	Apply a bundle.

Import flags. When the bundle contains custom games, a real import (not --dry-run) requires exactly one of --custom-games-use-defaults, --custom-games-decisions, or --no-custom-games; without one it stops with an error listing the three. The first two can’t be combined.

Flag	Effect
--dry-run	Show what would change.
--no-redirects	Skip redirects even if the bundle has them.
--no-custom-games	Skip custom games even if the bundle has them.
--custom-games-use-defaults	Add new names, replace existing ones.
--custom-games-decisions <plan>	Use a plan from custom-games-plan instead.

# On the old machine
savevault-cli settings export -o savevault-settings.toml
savevault-cli settings export --include-custom-games --include-redirects -o savevault-settings.toml

# On the new machine
savevault-cli settings preview savevault-settings.toml
savevault-cli settings import savevault-settings.toml --dry-run
savevault-cli settings import savevault-settings.toml --custom-games-use-defaults

# Decide per custom game
savevault-cli settings custom-games-plan savevault-settings.toml -o plan.toml
#   …edit plan.toml…
savevault-cli settings import savevault-settings.toml --custom-games-decisions plan.toml

# Preferences only
savevault-cli settings import savevault-settings.toml --no-redirects --no-custom-games

Importing a bundle with schedule.enabled = true re-registers the OS scheduler on the new machine. User theme files are not bundled; export them from the Themes page.

Install roots

roots

Non-Steam install folders — the <base> in database paths — stored in config.toml as additional_roots. Steam libraries are discovered separately.

Subcommand	Effect
list	Roots saved in config, with their kind and whether they’re locked (auto-discovered) or editable.
discover	What auto-discovery finds on this machine. Read-only.
rescan [--dry-run]	Merge discovered roots into config, sort, dedupe, save. Same as the GUI’s Rescan & Add Roots.

savevault-cli roots list
savevault-cli roots discover
savevault-cli roots rescan --dry-run
savevault-cli roots rescan

Run rescan after installing a new launcher. Root paths support globs and the <game> placeholder; see the install roots guide.

Scheduled backups

schedule

Register a backup pass with your OS scheduler — Task Scheduler on Windows, a systemd timer on Linux, launchd on macOS — so it runs even when the app is closed. Each pass scans, backs up only games whose saves changed, applies retention, optionally syncs to the cloud, and can check for app updates.

Subcommand	Effect
enable [flags]	Save the schedule and register it with the OS.
disable	Turn it off and deregister.
status	Show the current schedule.
history [--limit <n>]	Recent runs, newest first. Default 10, capped at 30.

enable flags:

Flag	Effect
--mode <daily|weekly|monthly|interval>	Default daily.
--time <HH:MM>	Time of day for calendar modes. Default 03:00.
--interval <hours>	For interval mode, e.g. 4h or 4. Default 4.
--weekdays <list>	For weekly: ISO numbers 1–7 (Mon = 1) and/or names, comma-separated: mon,wed,fri or 1,3,5.
--month-day <1-31>	For monthly. Default 1.
--games <name>	Only back up these games (repeatable). Default: all detected.

# Every night at 03:00
savevault-cli schedule enable

# Every 4 hours
savevault-cli schedule enable --mode interval --interval 4h

# Mon/Wed/Fri at 22:30
savevault-cli schedule enable --mode weekly --weekdays mon,wed,fri --time 22:30

# First of the month, only two games
savevault-cli schedule enable --mode monthly --month-day 1 --games "Elden Ring" --games "Stardew Valley"

savevault-cli schedule status
savevault-cli schedule history
savevault-cli schedule history --limit 30
savevault-cli schedule disable

Other schedule scalars — schedule.include_configs, schedule.output_dir, schedule.refresh_manifest_before_run — are set with config set, but schedule enable is what (re)registers the OS trigger, so run it again after changing the timing.

schedule-run

Run a single scheduled pass right now, in the foreground, printing its output. The OS scheduler itself fires the silent savevault-scheduled binary, which does the same work without a console window.

With the global --json flag it prints the pass report as JSON instead of the summary text. It exits 2 if any game’s backup failed, so an OS scheduler’s “last result” shows the failure.

savevault-cli schedule-run
savevault-cli --json schedule-run

Live Protection

live

Real-time rolling snapshots while games run, triggered by save-file writes or the checkpoint hotkey. The GUI runs the engine in the background; the CLI can run it too.

Subcommand	Effect
start [--game <name>]	Run the engine in this terminal until Ctrl+C. Monitors the configured list (or every detected game if the list is empty), or just one game.
status	Show Live Protection configuration.
snapshot [--label <text>]	Take an immediate snapshot of every monitored game. With --label, each snapshot is also pinned.
list [--game <name>]	List snapshots.
pin <id> [--label <text>]	Pin a snapshot so rolling cleanup keeps it.
unpin <id>	Unpin.
delete <id> [--force]	Delete a snapshot. Refuses pinned ones unless --force.
enable <game> / disable <game>	Add or remove one game from the monitor list (the GUI’s per-game toggle).
enable-all / disable-all	enable-all monitors every detected game and also sets live.enabled to true. disable-all only clears the monitor list; it leaves live.enabled as it was.

savevault-cli live status

# Choose what's monitored
savevault-cli live enable "Elden Ring"
savevault-cli live disable "Elden Ring"
savevault-cli live enable-all
savevault-cli live disable-all

# Run the engine from a terminal (Ctrl+C to stop)
savevault-cli live start
savevault-cli live start --game "Elden Ring"

# Manual snapshot right before something risky
savevault-cli live snapshot --label "before the mod install"

# Manage snapshots
savevault-cli live list
savevault-cli live list --game "Elden Ring"
savevault-cli live pin 3f9c2a1e --label "keep"
savevault-cli live unpin 3f9c2a1e
savevault-cli live delete 3f9c2a1e --force

Note

pin, unpin, and delete take either the full snapshot id or a prefix of it, so the 8-character ids that live list prints work directly. A prefix that matches more than one snapshot is rejected with the candidates listed; add more characters, or take the full id from savevault-cli --json live list.

The hotkey (live.hotkey, default Ctrl+Shift+S) and controller chord (live.controller_hotkey, default L3+R3) are set with config set. Snapshots live under <backup_dir>/snapshots/ unless live.snapshot_dir is set. See the Live Protection guide for how checkpoints behave with and without a game running.

Cloud backup

cloud

Bidirectional sync of your backup folder with your own cloud storage via rclone. Setup (provider sign-in, remote folder) happens in Settings → Off-site backup; the CLI runs and maintains it.

Subcommand	Effect
status	Configuration, which rclone is in use, its version, the active remote.
sync [--resync]	Run a bisync now. --resync re-initializes the pairing (needed after a manual change on one side). Exits 2 and prints the rclone log tail if the bisync fails.
install (alias repair)	Download and install the pinned managed rclone. For Lite builds, or to repair a broken managed copy.
reset	Clear remotes and reset cloud settings.

savevault-cli cloud status
savevault-cli cloud sync
savevault-cli cloud sync --resync
savevault-cli cloud install
savevault-cli cloud reset

Related keys for config set: cloud_backup.sync_after_backup, cloud_backup.sync_on_launch, cloud_backup.remote_path, cloud_backup.bisync_confirm_deletes, cloud_backup.scheduled_sync_skip_on_deletions, cloud_backup.sync_extra_args.

Notifications

notifications

Fire test OS notifications through the same headless path scheduled runs use. Bypasses your notification settings, so it’s the way to confirm toasts work at all.

Subcommand	Effect
list	The test kinds and where each one routes when clicked.
test <kind>	Fire one.
test --all [--delay-secs <n>]	Fire every kind, n seconds apart (default 3).

Kinds: manifest, manual-backup, manual-backup-cloud, smart-backup, scheduled-run, scheduled-failure, restore, cloud-sync, live-hotkey, app-update.

savevault-cli notifications list
savevault-cli notifications test scheduled-run
savevault-cli notifications test --all --delay-secs 5

Which real events notify is controlled by the notifications.* keys — see the configuration reference.

Diagnostics

diagnose

A one-paste support report for a single game. Read-only: it reads the state database (for the recent-backups list) but never writes to it, and it doesn’t modify the filesystem.

It includes the SaveVault version and edition, OS, config directory and log path; how the game was detected (source, resolved install roots, cache vs. fresh scan); every database path template with the candidates it resolved to on this machine, and for templates with no hits, why; the scanner’s implicit probes (Steam Cloud userdata and Wine/Proton prefix re-probes); the exact backup plan (the same body as backup --dry-run); exclusions in force; Live Protection status; and the last few backups on record.

savevault-cli --verbose diagnose "Elden Ring"
savevault-cli --json diagnose "Elden Ring"

Run it with --verbose before filing a “my save isn’t being backed up” issue and paste the output. See reporting a problem.

Launch wrapper

wrap

Run a game command with SaveVault protection wrapped around it: resolve which game is launching, optionally pull the latest cloud backup and restore the latest local backup first, launch and wait, then back up (and push to the cloud) once it exits. Fail-open: a SaveVault-side error never blocks the launch.

savevault-cli wrap [--game <name>] [--restore <auto|ask|off>] [--no-sync] [--no-backup] [--no-notify] [--no-hotkey] [--gui] [--force] -- <command> [args...]

Flag	Effect
--game <name>	Skip inference; protect this game.
--restore <auto|ask|off>	Pre-launch restore of the latest backup. Default ask. A backup that misses another device’s newer progress is always asked about, and one made on another OS is never restored here.
--no-sync	Skip the pre-launch and post-backup cloud sync.
--no-backup	Skip the post-exit backup.
--no-notify	Suppress routine OS notifications for this run.
--no-hotkey	Don’t start wrap’s own checkpoint hotkey thread or controller-chord poller for this session. The session marker is still written, so a running GUI engine can still checkpoint the game.
--gui	Native dialogs instead of terminal prompts. Implied for savevault-wrap.
--force	Never ask: launch an unrecognized game unprotected, and treat ask as off.
-- <command>	The game command. Everything after -- is passed through untouched.

savevault-cli wrap -- "C:\Games\Elden Ring\eldenring.exe"
savevault-cli wrap --game "Elden Ring" --restore auto -- "C:\Games\Elden Ring\eldenring.exe"

# Steam launch options (Windows): silent sibling binary
"C:\Program Files\SaveVault\savevault-wrap.exe" -- %command%

# Steam launch options (Linux / SteamOS)
savevault-wrap --restore auto -- %command%

Exit code is always the game’s own, except 1 (couldn’t spawn), 2 (no command), 3 (you declined to launch an unrecognized game), 4 (pre-launch restore failed). The full flow, resolution order, consent model, and launcher recipes for Steam, Heroic, Lutris, and Playnite are on the launch wrapper page.

JSON output

--json produces structured output for: scan, list, backup, backup-preview, restore, list-files, explain, backups, prune, verify, exclusions, restore-excludes, add, remove, detection, manifest, config, roots, diagnose, and schedule-run (which prints its pass report).

Three families support it only on some subcommands; the rest print text:

• settings: preview only. export, import, and custom-games-plan print text.
• live: status and list only. start, snapshot, pin, unpin, delete, enable, disable, enable-all, and disable-all print text.
• redirects: show only, and only when at least one rule exists; with no rules it prints the text hint. add, remove, clear, path, export, and import print text.

It is ignored by restore-batch, schedule, cloud, notifications, and wrap, which print human-readable text only.

# Names of every detected game, one per line, with jq
savevault-cli --json list --installed | jq -r '.[].name'

# Fail a CI step if any archive is corrupt
savevault-cli --json verify --all

Commands exit non-zero on error, so they’re safe to chain in scripts.