agents-store restic CLI Reference
Complete command, flag, and environment-variable reference. For task-oriented usage see setup, repository-setup, backup-script, verify-backup, disaster-recovery, and troubleshoot. Full docs: https://restic.readthedocs.io/
Global form
restic [global flags] <command> [command flags] [args]
Global flags: -r/--repo, --repository-file, --password-file, --password-command, --cache-dir, --no-cache, --json, --quiet, --verbose, -o <key=value> (backend options, e.g. -o s3.region=auto).
Command index
| Command | Purpose |
|---|---|
restic init |
Create a new (encrypted) repository |
restic backup |
Create a snapshot of files/dirs |
restic snapshots |
List snapshots |
restic ls |
List files within a snapshot |
restic find |
Search for files across snapshots |
restic restore |
Restore files from a snapshot |
restic dump |
Stream a file/dir from a snapshot to stdout |
restic forget |
Remove snapshots per a retention policy |
restic prune |
Repack and reclaim unreferenced data |
restic check |
Verify repository integrity |
restic stats |
Repository / snapshot statistics |
restic cat |
Output internal objects (e.g. cat config) |
restic unlock |
Remove stale locks |
restic list |
List object IDs (locks, snapshots, packs, ...) |
restic copy |
Copy snapshots between repositories |
restic migrate |
Apply repo migrations (e.g. upgrade_repo_v2) |
restic diff |
Diff two snapshots |
restic tag |
Add/remove/replace snapshot tags |
restic rewrite |
Rewrite snapshots (e.g. drop paths) |
restic repair |
Repair index / snapshots / packs |
restic self-update |
Update the restic binary |
restic key |
Manage repository passwords/keys |
init
restic init [--repository-version <2>] [--from-repository ... (copy keys)]
backup
restic backup [flags] [PATH...]
| Flag | Notes |
|---|---|
--tag <t> |
Tag the snapshot (repeatable) |
--files-from <f> |
Read include paths from a file (one per line) |
--files-from-verbatim <f> |
Like above, no shell interpretation |
--files-from-raw <f> |
NUL-separated list (safest for scripts) |
--exclude <pat> / --iexclude |
Exclude pattern (case-insensitive variant) |
--exclude-file <f> |
Exclude patterns from a file |
--exclude-caches |
Skip dirs containing CACHEDIR.TAG |
--exclude-larger-than <size> |
Skip files bigger than e.g. 1G |
--one-file-system |
Don't cross mount points (off by default) |
--stdin-from-command -- <cmd> |
Back up a command's stdout |
--stdin-filename <name> |
Name for the stdin stream |
--dry-run / -n |
Show what would happen |
--host <h> |
Override hostname recorded in the snapshot |
snapshots / ls / find / diff / stats
restic snapshots [--latest <n>] [--host <h>] [--path <p>] [--tag <t>] [--group-by host,path,tags] [--json]
restic ls <snapshotID|latest> [path]
restic find <pattern> [--snapshot <id>]
restic diff <snap1> <snap2>
restic stats [snapshotID|latest] [--mode restore-size|files-by-contents|raw-data|blobs-per-file]
restore / dump
restic restore <snapshotID|latest> --target <dir> [--include <p>] [--exclude <p>]
[--iinclude/--iexclude] [--include-file <f>] [--overwrite always|if-changed|if-newer|never]
[--delete] [--sparse] [--dry-run -vv] [--host <h>] [--path <p>]
restic restore <snapshotID>:<subpath> --target <dir> # restore a subtree
restic dump <snapshotID|latest> <path> # to stdout
forget / prune
restic forget [selection] [policy] [--prune] [--dry-run] [--group-by host,path,tags]
Retention policy flags: --keep-last <n>, --keep-hourly, --keep-daily, --keep-weekly, --keep-monthly, --keep-yearly, --keep-within <dur>, --keep-within-daily/-weekly/-monthly <dur>, --keep-tag <t>. Selection: --tag, --host, --path.
restic prune [--max-unused <limit|unlimited>] [--max-repack-size <size>] [--dry-run]
check
restic check [--read-data] [--read-data-subset <n%|nM|k/N>] [--with-cache]
unlock / list / cat / migrate / repair
restic unlock [--remove-all]
restic list <locks|snapshots|index|packs|keys>
restic cat <config|masterkey|snapshot <id>|...>
restic migrate [upgrade_repo_v2]
restic repair <index|snapshots|packs>
restic rebuild-index # older alias of `repair index`
key / copy / self-update
restic key list|add|remove|passwd
restic copy --from-repo <repo> --from-password-file <f> [snapshotID...]
restic self-update [--output <path>]
Environment variables
| Variable | Purpose |
|---|---|
RESTIC_REPOSITORY |
Repository location (e.g. s3:https://<acc>.r2.cloudflarestorage.com/<bucket>) |
RESTIC_REPOSITORY_FILE |
File containing the repo location |
RESTIC_PASSWORD |
Repository password (avoid in scripts/history) |
RESTIC_PASSWORD_FILE |
File containing the password (mode 600) |
RESTIC_PASSWORD_COMMAND |
Command that prints the password |
RESTIC_COMPRESSION |
off / auto (default) / max (repo v2) |
RESTIC_CACHE_DIR |
Local cache directory |
RESTIC_PACK_SIZE |
Target pack size (MiB) |
RESTIC_PROGRESS_FPS |
Progress refresh rate |
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY |
S3/R2 credentials |
AWS_DEFAULT_REGION |
S3 region — auto for R2 |
AWS_SESSION_TOKEN |
Temporary STS token |
Backend options (-o): s3.region, s3.bucket-lookup=path|dns, s3.connections=<n>, s3.storage-class, s3.list-objects-v1=true.
Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | fatal error (backup: no snapshot created) |
| 3 | partial — some files unreadable, snapshot created |
| 10 | repository does not exist (≥0.17) |
| 11 | repository locked |
| 12 | wrong password (≥0.17.1) |
| 130 | cancelled (SIGINT/SIGTERM) |
Version notes
- Compression + repository format v2 require restic ≥ 0.14.
- Exit codes 10 / 11 / 12 were added in 0.17.x; older binaries return 1.
restic repair indexreplacedrestic rebuild-index(the old name still works).