--- created: '2026-04-16T04:07:10+00:00' id: 34f7f22e-f842-40e8-bbc2-1dff12c1b87e keywords: - autorestic - restic - YAML - backup - automation - cron - hooks - Docker volumes - snapshot copy - retention policy - multi-backend - cupcakearmy links: [] modified: '2026-04-16T04:07:10+00:00' summary: Reference for Autorestic — a config-driven CLI wrapper around restic that simplifies backup management via YAML configuration, multi-backend orchestration, hooks, cron scheduling, and Docker volume support. tags: - backup - restic - autorestic - automation - CLI - YAML - reference title: Autorestic Reference --- --- id: autorestic title: Autorestic Reference created: 2025-07-10 modified: 2025-07-10 tags: - backup - restic - autorestic - automation - CLI - YAML - reference links: - reference/restic.md - reference/docker-compose.md --- # Autorestic — Config-Driven CLI for Restic **URL:** https://autorestic.vercel.app/ **GitHub:** https://github.com/cupcakearmy/autorestic **License:** MIT **Platforms:** Linux, macOS (Windows NOT supported) ## Overview Autorestic is a high-level CLI wrapper around restic that simplifies backup management through YAML configuration files. While restic is powerful, its CLI becomes unwieldy when managing many backup locations across multiple backends. Autorestic provides: - **YAML config files** — no complex CLI flags - **Multiple backends per location** — backup to several destinations simultaneously - **Snapshot policies** — retention/forget rules per location - **Before/after hooks** — run commands around backups - **Cron job scheduling** — built-in automatic scheduling - **Docker volume support** — backup/restore Docker volumes - **Copy optimization** — copy snapshots between backends without re-reading source - **Generated shell completions** — bash, zsh, fish, powershell ## Installation ### Script (Recommended) ```bash curl -s https://raw.githubusercontent.com/cupcakearmy/autorestic/master/install.sh | bash ``` Requires `bash`, `wget`, and `bzip2`. ### Package Managers | Platform | Command | |---|---| | macOS | `brew install autorestic` | | Fedora | `dnf install autorestic` | | Arch Linux | AUR package | ### Docker ```bash docker pull cupcakearmy/autorestic ``` ### Manual Download binary from GitHub releases to `/usr/local/bin` (autoupdates still work). ## Configuration Autorestic uses a YAML config file. Default locations: - `~/.autorestic.yml` - `$PWD/.autorestic.yml` Custom location: `-c path/to/config.yml` ### Config Structure ```yaml version: 2 global: # Optional global settings forget: # Default retention policy keep-daily: 30 keep-weekly: 52 backends: # Backend definitions local: type: local path: /tmp/backups key: some-secret-password b2: type: b2 path: my-bucket key: another-secret s3: type: s3 path: s3.amazonaws.com/bucket key: s3-secret env: # Custom environment variables AWS_ACCESS_KEY_ID: key AWS_SECRET_ACCESS_KEY: secret locations: # Backup locations home: from: /home/user to: # Single or multiple backends - local - b2 hooks: before: echo "Starting backup" after: echo "Done!" success: echo "Success!" failure: echo "Failed!" cron: "0 3 * * *" # Cron expression for scheduling forget: prune # Auto-forget after backup (use "yes" to forget without prune) options: forget: keep-last: 10 keep-daily: 14 backup: exclude: - '*.tmp' exclude-file: .gitignore docker-volumes: from: docker-volumes:/ # Docker volume syntax to: local ``` ### Backend Names Names MUST be lower case. If no key is defined, autorestic auto-generates one and writes it back to the config. To prevent this, set `requireKey: true`. ### Location Names Names MUST be lower case. Location names are used with `-l` flags. ## Locations The `from` field is the source (can be a single string or an array of strings). Paths can be absolute, relative to the config file, or use `~` for home directory. The `to` field is one or more backends (defined in the `backends` section). ### Location@Backend Syntax Select a specific backend for a location: ```bash autorestic backup -l location@backend ``` ## Hooks Five hook stages available: 1. **prevalidate** — before checking if backup location is valid (e.g., to mount filesystem) 2. **before** — after validation check, before backup runs 3. **after** — after backup completes (success or failure) 4. **success** — only on successful backup 5. **failure** — only on failed backup **Flow:** `prevalidate` → check location → `before` → backup → `after` → `success`/`failure` If `prevalidate` or `before` fails, backup and `after` are skipped, only `failure` runs. ### Environment Variables in Hooks - `AUTORESTIC_LOCATION` — location name (all hooks) - After/success hooks additionally get per-backend metadata: - `AUTORESTIC___` where N is the backend execution order Available metadata: `SNAPSHOT_ID`, `PARENT_SNAPSHOT_ID`, `FILES_ADDED`, `FILES_CHANGED`, `FILES_UNMODIFIED`, `DIRS_ADDED`, `DIRS_CHANGED`, `DIRS_UNMODIFIED`, `ADDED_SIZE`, `PROCESSED_FILES`, `PROCESSED_SIZE`, `PROCESSED_DURATION` ## Location Options Pass native restic flags per command: ```yaml locations: my-location: from: /data to: backend options: backup: tag: - foo - bar one-file-system: true forget: keep-last: 5 ``` **Priority:** location > backend > global ## Copy Optimization Instead of backing up to multiple backends separately, copy snapshots between backends: ```yaml locations: my-location: from: /data to: - fast-backend # backup here - slow-backend # backup here copy: fast-backend: - slow-backend # copy from fast to slow (no re-read of source) ``` ## Excluding Files ```yaml locations: my-location: from: /data to: my-backend options: backup: exclude: - '*.nope' - '*.abc' exclude-file: .gitignore ``` ## Forget/Retention Policies ```yaml locations: etc: from: /etc to: local forget: prune # auto-forget after backup options: forget: keep-last: 5 keep-hourly: 3 keep-daily: 4 keep-weekly: 1 keep-monthly: 12 keep-yearly: 7 keep-within: "14d" ``` Global defaults: ```yaml global: forget: keep-daily: 30 keep-weekly: 52 ``` ## Cron Jobs Add a `cron` expression to any location: ```yaml locations: home: from: /home/user to: local cron: "0 3 * * *" # daily at 3 AM ``` Then install the cron runner (once, regardless of number of locations): ```bash # In crontab (trigger every 5 minutes recommended): */5 * * * * autorestic --ci cron # or: */5 * * * * autorestic -c /path/to/config.yml --ci cron ``` Manual backups with `autorestic backup` don't affect the cron timeline. ## Docker Volumes Backup Docker volumes using special `from` syntax: ```yaml locations: db-volume: from: docker-volumes:my_volume_name to: local ``` ## CLI Reference ### General ```bash autorestic info # show config summary autorestic check # verify config and initialize backends autorestic -c config.yml ... # use custom config file ``` ### Backup ```bash autorestic backup -a # backup all locations autorestic backup -l home # backup specific location autorestic backup -l home -l etc # backup multiple locations autorestic backup -l home@b2 # backup location to specific backend ``` ### Restore ```bash autorestic restore -l home --to /path/where/to/restore autorestic restore -l home --to /path --force # overwrite existing data ``` If a location has multiple backends, autorestic uses the first one. Default snapshot is `latest`. ### Forget/Prune ```bash autorestic forget -a # apply retention policy to all autorestic forget -l home # apply to specific location autorestic forget -a --dry-run # preview only autorestic forget -a --prune # also prune (free disk space) ``` ### Exec (Run Native Restic Commands) ```bash autorestic exec -a -- snapshots # list all snapshots autorestic exec -av -- snapshots # verbose autorestic exec -b local -- snapshots # specific backend autorestic exec -a -- check --read-data # any restic command ``` ### Other Commands | Command | Description | |---|---| | `autorestic cron` | Run cron-triggered backups | | `autorestic unlock` | Remove stale locks | | `autorestic upgrade` | Update autorestic | | `autorestic install` | Install restic binary | | `autorestic uninstall` | Uninstall restic binary | | `autorestic completion` | Generate shell completions | ## Relationship to Restic Autorestic is purely a wrapper — all actual backup/restore/encryption work is done by restic. Autorestic adds: - YAML configuration management - Multi-backend orchestration - Hook execution - Cron scheduling - Snapshot copy optimization - Simplified CLI for common operations For all restic concepts (encryption, deduplication, backends, etc.), see the [Restic Reference](reference/restic.md). ## See Also - [Restic Reference](reference/restic.md) - [Docker Compose Reference](reference/docker-compose.md)