arq_restore pulls files back out of an Arq backup from the command line

A restore path for when the Arq app is not an option

The project description calls arq_restore a command-line utility for restoring from Arq backups, and the README is more specific: it is an open source command line macOS utility for restoring from backups created by any version of Arq, supporting Arq 5, 6 and 7 backup formats. The macOS qualifier is not incidental, because the repository is an Xcode project with Objective-C sources, and the backup formats are macOS backups. So the audience is a person or a script on a Mac who has Arq backups and needs the data back. The situation that makes this useful is the failure case. If the machine that was backed up is gone and the backup is in a bucket or on a volume, then the restore path normally goes through the Arq application itself, which needs a GUI session and an interactive operator, and a script cannot drive it. A command line tool that takes a target, a computer identifier, a folder identifier and a destination removes both of those obstacles. The tool is written by the people who make Arq, since the licence names Haystack Software LLC, and the copyright runs from 2009 to 2026, so the format knowledge is first hand rather than reverse engineered.

Targets, computers, folders, tree, restore

The command surface is a five step walk from a bucket to files on disk, and each step exists because the backup format is layered. A target is a named pointer to where your backups are stored, and you create one for AWS S3 by giving a nickname and an access key id, with the secret key then prompted for.

arq_restore addtarget <nickname> aws <access_key_id>

For a local filesystem or network volume the target is the same idea with a path.

arq_restore addtarget <nickname> local <path>

Targets are listed and removed with listtargets and deletetarget, so the credential you registered stays on the machine and can be withdrawn. From a target you list the machines, and the list is where the two supported format generations show up, since it lists all Arq 5 computer UUIDs and Arq 7 backup plan UUIDs found at the target, and each entry shows the UUID you need for subsequent commands. That identifier is then used to list the backed up folders and their folder UUIDs, and the folder UUID is used to print the file tree from the most recent complete backup of that folder. Only the most recent complete backup is ever used, which is a deliberate simplification and also a limitation, since there is no option in the documented commands to reach an older point in time.

The restore command and what it actually brings back

The last step takes the target, the computer or plan UUID, the folder UUID and an optional destination path.

arq_restore restore <nickname> <uuid> <folder_uuid> [destination_path]

The destination defaults to the original path, which is what you want when the machine came back with an empty disk, and the README is specific about what is preserved: file contents, permissions, timestamps and extended attributes are all restored. Extended attributes are the part worth pausing on, because on macOS they carry resource forks, Finder metadata and quarantine flags, and a restore that drops them produces files that behave oddly in applications that rely on them. The tree and the folder listings are also only as good as the format parsing underneath. The README links two format documents in the repository root, arq5_data_format.txt for the Arq 5 backup data format and arq7_data_format.html for the Arq 7 one, and those documents are the closest thing to a specification a reader gets, since the tool parses those structures directly. The repository listing backs this up, with per-format directories named arq6restore/, arq7restore/, s3restore/, s3glacierrestore/ and glacierrestore/, plus shared directories commonrestore/, cocoastack/ and repo/, and low level files such as BlobKey, BlobKeyIO, Bucket, BucketExclude and CacheOwnership that are clearly the storage layer, plus a vendored sqlite3 and a fmdb/ directory, which is the Objective-C SQLite wrapper.

Building it: Xcode, and a vendored dependency tree

There is no package manager install step in the README, which is consistent with the project being an Xcode project rather than a Homebrew formula. The documented build is to open arq_restore.xcodeproj in Xcode and choose Product and Build, or from the command line.

xcodebuild -project arq_restore.xcodeproj -scheme arq_restore -configuration Release

The binary lands at build/Release/arq_restore. Two details in the repository listing are worth knowing before you start. First, the source tree is not self contained in the modern sense. There is a 3rdparty/ directory, a CocoaLumberjack/ directory for the logging framework, and vendored copies of sqlite3.c and sqlite3.h with an fmdb/ wrapper on top, so the build is a full compile of third party code rather than a dependency resolution. Second, the .m and .h pairs at the root are the command layer, ArqRestoreCommand, plus the ArqSalt, BackupSet, Bucket, ReflogEntry, System, Target and TargetFactory types, with TargetFactory and TargetConnection explaining the target abstraction that lets one command surface serve both S3 and a local volume. The logging levels are configurable with a flag that must be passed immediately after the program name, and the valid values are error, warn, info, detail and debug, so the debugging story is the usual verbosity flag rather than a configuration file.

arq_restore -l debug listcomputers mynas

The limits: macOS, one backup point, and a closed source format

Three constraints shape what this tool can be used for. The first is the platform, since it is a macOS utility built as an Xcode project, so a Linux or Windows administrator cannot use it, and even a Mac administrator has to have the toolchain to compile it. The second is the model of the data. Every listing command works on the most recent complete backup of a folder, and the restore command has no option to select an earlier backup or a point in time, so this is a recovery tool rather than a browsing tool. If you need the version of a file as it was last March, Arq's own application is the place to look. The third and most serious is the format dependency. The tool parses Arq's internal data structures, and those structures belong to a closed source commercial product whose internal layout is not covered by any published compatibility promise, which is why the README ships the two format documents and why a change on the Arq side would surface as a parse failure rather than as a warning. The licence reinforces the relationship, since the copyright holder is the Arq vendor and the terms include a clause about the names of PhotoMinds LLC and Haystack Software. In practice the tool is a well supported path for Arq 5, 6 and 7 backups, but it is not insulated from its upstream.

Editorial conclusion

arq_restore suits a Mac administrator who has Arq backups and a reason to read them without the Arq application, for example a dead machine whose data lives only in the backup, or a scripted recovery where a human should not have to click through a restore wizard. It is the wrong tool for a general backup strategy, since it only understands Arq's own formats, and it is the wrong tool for cross-cloud restores, because the README is explicit that you have to download the backup data to a local path first and point the tool at that. Before you rely on it, test a restore from a backup you already know the contents of, and check the published data format documents, arq5_data_format.txt and arq7_data_format.html, since the tool parses those structures directly and Arq is a closed source product whose format may change.

Frequently asked questions

Official sources

1. arqbackup/arq_restore on GitHub
2. Issues
3. Project website
4. README
5. Releases