VuongKB/reference/autorestic.md

---
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_<METADATA>_<BACKEND>_<N>` 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)