autorestic wraps restic in a YAML config for multi-backend backups

A wrapper, not a replacement, and the distinction decides everything

autorestic is a config driven backup command line tool for restic, written in Go. The README frames it plainly: it is a wrapper around restic, and while restic is capable, the restic cli can be a bit overwhelming and difficult to manage if you have many different locations that you want to back up to multiple locations. The utility is aimed at making that easier.

That framing matters for how you should evaluate it. Every backup, every repository, every snapshot, every prune in autorestic is a restic operation underneath. The value autorestic adds is the configuration layer: YAML config files and no CLI, snapshot policies and pruning, backups to multiple backends, before and after hooks, exclude patterns, cron jobs, and generated shell completions for bash, zsh, fish and powershell.

The feature list also states that backups are fully encrypted, which is inherited from restic's own design rather than being an autorestic feature. Similarly, incremental backups with minimal space usage and deduplication are restic behaviours. The topics attached to the repository, backup, config-driven, deduplication, incremental, pruning and restic, describe the same thing.

The audience is an operator with several things to back up. If you have one directory and one S3 bucket, restic directly with a shell script is entirely adequate. If you have six locations, four backends, retention rules per location and a set of directories to exclude, the state you would otherwise keep in shell history starts to exceed what anyone can remember.

There is also a documentation site at autorestic.vercel.app, and support through the repository discussions page and a Discord channel.

The Go dependency list shows the config layer is cobra, viper and cron

The go.mod tells you what autorestic is made of, and it is a compact list. The CLI framework is spf13/cobra at 1.4.0, and configuration handling is spf13/viper at 1.11.0, with the usual viper transitive dependencies for TOML, YAML, ini, env and properties formats.

Viper is the reason the configuration is flexible. It reads YAML, but it also supports JSON, TOML, ini, environment variables and a .env file, since joho/godotenv and subosito/gotenv are in the dependency list, and mitchellh/go-homedir and spf13/afero handle locating files under the home directory and abstracting the filesystem. In practice that means a value can come from a config file or from an environment variable, which is what you need when the config holds a repository password.

Scheduling comes from robfig/cron at 1.2.0, which is what enables the cron job feature for automatic backups rather than requiring an external scheduler. Terminal output uses fatih/color, mattn/go-colorable and mattn/go-isatty, so the CLI degrades to plain text when the output is not a terminal, and buger/goterm handles terminal drawing. Version checks against the restic binary use blang/semver/v4.

The module targets Go 1.26.1, and the repository root holds a main.go, a cmd/ directory for the command tree, an internal/ directory for the implementation, a build/ directory, docs/, a CHANGELOG.md, a DEVELOPMENT.md, a Dockerfile, an install.sh and a mise.toml for toolchain version pinning. Tests use stretchr/testify.

The Docker image pins restic 0.17.3 and layers tools on top

The Dockerfile is short and says something about how the project is meant to be deployed. It builds the Go binary in a golang:1.25-alpine builder stage, then puts that binary into a restic/restic:0.17.3 base image:

FROM restic/restic:0.17.3
RUN apk add --no-cache rclone bash curl docker-cli
COPY --from=builder /app/autorestic /usr/bin/autorestic
ENTRYPOINT []
CMD [ "autorestic" ]

The additions are the interesting part. rclone is there because restic uses it for some backends, bash and curl are general purpose, and docker-cli is included so the container can drive the Docker daemon, which pairs with the backup and restore of Docker volumes feature.

Note the restic version pin. The image ships restic 0.17.3, and since autorestic is a wrapper that shells out to the restic binary, that pin determines both the repository format compatibility and the feature set available to you. If you run autorestic against a repository written by a much newer restic, the older binary inside the container is what will read it.

The ENTRYPOINT is cleared and the CMD is autorestic, which means the container is designed to take a subcommand as arguments rather than to run a fixed command. The two-stage build keeps the runtime image free of the Go toolchain, and the .dockerignore at the repository root keeps the build context small.

The install.sh script at the root is the non-Docker path, and mise.toml pins the Go toolchain version for developers, which is consistent with the go.mod directive of 1.26.1.

Hooks, excludes and cron are the features that change the workflow

The feature list has three entries that make autorestic a different way of working rather than a shorter spelling of restic.

Before and after backup hooks let you run your own commands around a backup, which is how you stop a database for a consistent dump or dump a database to a file before the snapshot runs. Exclude pattern and file support means the ignore rules live in the config next to the location they apply to, rather than in a separate exclude file that restic needs to be pointed at.

Cron jobs for automatic backup is the one that changes the deployment shape. Because robfig/cron is embedded, autorestic can schedule its own runs. Whether that is a good idea is a separate question from whether it works. An external scheduler, whether cron on the host or a systemd timer, gives you the same result with the scheduling state in the place your operations team already looks, plus the usual systemd features for logging and failure notification. Embedding the scheduler means the schedule lives in the config file, which is convenient when the config is the source of truth, and less convenient when you want the backup to run even if the wrapper is not the thing that starts.

The last feature, backup and restore of Docker volumes, is what the docker-cli in the image is for. It is also the feature with the sharpest edge, since it needs access to the Docker socket to reach the volumes, and the README does not describe how that access is scoped.

Generated completions for bash, zsh, fish and powershell are the small quality of life item. Since the tool is described as no CLI, in the sense that you configure it rather than pass flags, the completions matter less than they would for a tool with a large flag surface.

Version 1.8.3 from 2024, with the last push in April 2026

The release record is worth reading carefully. The recent releases are v1.8.3 from 2024-08-28, v1.8.2 from 2024-03-28 and v1.8.1 from 2024-03-13. The repository is not archived, and the last push was on 2026-04-05.

So the last tagged release is more than two years old, while the repository has seen commits as recently as April 2026. That gap is the kind of thing to check before you depend on the tool, because it tells you the released binary and the working tree are not the same thing. A build from the tip of master may contain fixes that never reached a tagged release, and if you install the released version you may be missing them.

The licence is Apache-2.0, with the LICENSE file in the repository as the authoritative text. That is a permissive licence with no copyleft obligations on your configuration or scripts, and this is a licensing statement rather than legal advice.

The dependency picture is another maintenance signal, and it is a mixed one. Go 1.26.1 in go.mod is current, and the toolchain has moved forward. But the pinned versions of several libraries are noticeably old: robfig/cron is at 1.2.0, spf13/cobra at 1.4.0, spf13/viper at 1.11.0, and fatih/color at 1.13.0. Older is not the same as unmaintained, and pinning is often deliberate to avoid breaking changes in a CLI tool, but it does mean you are not getting the fixes those libraries have accumulated since.

There is a CHANGELOG.md in the repository, which is the place to look for what changed between the 1.8.x tags and the current master.

The alternative is a restic script, and the difference is where the state lives

The honest alternative to autorestic is a shell script that calls restic, possibly a small generated one per location, driven by cron or a systemd timer. It has no dependencies, it is transparent, and you can read every line.

The difference in approach is where the state of the backup lives. In a script, the state is the script itself and the crontab. You learn what runs when by reading the script and the crontab, and the failure mode of that approach is that the two drift apart over a year of edits.

In autorestic, the state is one YAML file that describes the locations, the backends, the snapshot policies, the excludes and the hooks. The scheduled runs and the retention rules live next to each other, which is what makes a configuration review useful. The cost is an extra layer: a bug or a misconfigured key in that file affects many locations at once, and the error surfaces from autorestic rather than from restic, so you need to read two documentations to diagnose a backup that did not run.

The other alternative worth naming is a dedicated backup orchestration tool with scheduling, retention and reporting built in. Those give you a dashboard and a history of what ran, which autorestic does not provide, and they ask you to adopt their model of what a backup job is. If you already have one in place, autorestic is a smaller tool that may be a better fit for a handful of restic repositories.

The deciding question is simple. If you can describe your backup setup in one YAML file and you want that file to be the thing you review, autorestic fits. If you want to see what ran last night, a tool with a report is a better match.

Editorial conclusion

Adopt autorestic if you run restic on more than one location and the long flag invocations have become hard to keep straight, and if you want pruning policy and scheduling defined in one file you can read. Do not adopt it if your backups are a single restic repository with a simple cron entry, because the configuration layer adds a second thing to learn for no gain. Before you deploy, confirm the restic binary is on the PATH, since autorestic drives it rather than replacing it, and decide whether the Docker image is acceptable for your setup, since it pins restic 0.17.3 and adds rclone, curl, bash and the docker CLI on top.

Frequently asked questions

Official sources

1. cupcakearmy/autorestic on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases