← mirrortools
MIRROR(1) General Commands Manual MIRROR(1)

mirror — mirror internet accounts and services to local disk

mirror [method] [flags] source [destdir]

mirror queue subcommand [arguments]

mirror submit [flags] source [destdir]

mirror method -h

mirror version

mirror copies what source names into the local directory destdir, which is created if needed. The method says what kind of source it is, and what source means: a URL, a server, an account or an item identifier. Each method has its own flags, which come after the method name; mirror method -h lists them.

The method can be left out when source says what it is:

archiveorg
... and /download/... URLs
groupsio
... URLs
ftp
and ftps:// URLs
git
and ssh:// URLs, git@host:path, *.git URLs, and Git repositories served over http:// or https://
gopher
URLs
sourceforge
... URLs
rsync
URLs and host::module sources
http
any other http:// or https:// URL
The flags then come before source, as they would after the method name.

The destdir can be left out when the configuration file, described in CONFIGURATION, names a default one.

Running mirror again with the same arguments brings the copy up to date, or picks up where an interrupted run stopped. Downloads are written under a temporary name and renamed into place once complete, so an interrupted run never leaves a truncated file behind under the real name.

Passwords are read from a file named with -password-file, never from the command line, so they stay out of the process list and the shell history. The file holds the password on one line.

mirror version prints the version.

Downloads every file of an Internet Archive item over HTTPS. source is a https://archive.org/details/id or https://archive.org/download/id URL, or the bare id. The files land in destdir/id, with their md5 checksums verified where the item lists them and their modification times taken from the item's file listing. A .done file is written once every file is complete, and a later run skips the item.

Check the item again even if it is marked done.
duration
Wait duration, such as 1s or 500ms, between requests. The default is not to wait.
n
Try a request again up to n times, 5 by default, when it fails with status 429 or 5xx, a network error or a bad checksum. The wait before each retry doubles from 2 seconds up to 10 minutes, unless the server's ‘Retry-After’ header asks for a different one.

Recursively mirrors a directory, or a single file, of an FTP server. source is ftp://[user[:password]@]host[:port]path, or ftps:// for implicit TLS (port 990). Files land in destdir/host/path. Directories are listed with MLSD where the server supports it, and LIST otherwise. Symbolic links that LIST reports are recreated locally. Interrupted downloads are resumed with REST.

name
Log in as name. The default is the user in the URL, or anonymous.
file
Read the password from file.
Upgrade the connection with AUTH TLS (explicit FTPS).
List every directory again, and download files whose size or modification time changed, files that are missing locally, and files that failed permanently before.

Mirrors a Git repository with git clone, or updates an existing clone in place with git fetch --prune --tags and fast-forwards the checked-out branch. An existing bare clone at the target path is converted in place to a non-bare working-tree clone without re-downloading objects. source is a https://, http://, git:// or ssh:// repository URL, or [user@]host:path. The repository lands in destdir/host/path, with any trailing .git stripped from path.

Recursively mirrors a Gopher menu tree. source is a gopher:// URL, such as gopher://host/1/menu. Files land in destdir/host/selector, and the info lines of each menu in a 00README file. Only items on the same host and port, below the starting selector, are followed.

Downloads a Google Photos library in original quality, using the browser session that -cookies holds. source is the account's email address, which is only used for logging. Files land in destdir/YYYY/MM by the date they were taken.

file
Cookies for photos.google.com: a Netscape cookies.txt export, or on macOS a .binarycookies file such as Safari's. The default is cookies.txt.
YYYY-MM-DD
Only items taken on or after this date.
YYYY-MM-DD
Only items taken on or before this date.
duration
Only items taken in the last duration, such as 30d, 2w, 6m or 1y. Cannot be combined with -after.
=bool
Also download the RAW companion of a Pixel RAW+JPEG pair. On by default.

Downloads every file in a groups.io group's Files section. source is the group's URL, https://groups.io/g/name, or the URL of any page under it, or just its short name, name. Files land in destdir/name.

address
The groups.io account to log in with. Required.
file
Read the account's password from file. Required.

Recursively mirrors everything under a path of an HTTP or HTTPS server. source is a URL; everything under its directory, after redirects, is mirrored. Files land in destdir/host/path; a URL ending in ‘/’ is saved as index.html. Links are followed only on the same scheme and host and under that path, but the images, stylesheets and scripts of every saved page are fetched from wherever they are. Directory listings generated by the server are only used to find files: they are not saved, and their sorting links are not followed.

Check everything already mirrored again with conditional requests, read directory listings again for new files, and retry URLs that failed with a 4xx status.
duration
Wait duration, such as 1s or 500ms, between requests.

Downloads iCloud Photos originals. source is the Apple ID. Signing in may ask for a two-factor code; the session is saved, so later runs usually don't need the password again. Files land in destdir/YYYY/MM by the date they were taken.

file
Read the Apple ID password from file. Only needed when there is no valid saved session.
dir
Where to save the session. The default is a directory per account under the user's cache directory.
name
The album to mirror. The default is “All Photos”.
=bool
Also download the video of a Live Photo. On by default.
, -before, -last
As for gphotos.

Mirrors the mail of an IMAP account, one Maildir per folder. source is host or host:port; the connection always uses TLS, on port 993 by default. Each folder lands in destdir/folder, following the server's folder hierarchy. Messages already present are not downloaded again.

name
The account to log in as. Required.
file
Read the account's password from file. Required.
folder
Mirror only folder, directly into destdir.

Mirrors an rsync source in archive mode, like rsync -a. source is rsync://[user@]host[:port]/module[/path] or [user@]host::module[/path] for an rsync daemon (anonymous modules only), or [user@]host:path over ssh(1). As with rsync(1), destdir is the destination itself, and a trailing slash on the source path copies the directory's contents rather than the directory.

Delete local files that no longer exist on the remote side.

Downloads every file in the files area of a SourceForge project, and none of the site's other pages. source is a project URL, https://sourceforge.net/projects/name/, for the whole files area; the URL of a folder in it, https://sourceforge.net/projects/name/files/folder/, for that folder and everything under it; or the URL of a file in it, for that file. The files land in destdir/name, in the folders they are in on SourceForge, with their md5 checksums verified and their modification times set to when they were uploaded. A later run downloads only files that are new or no longer match their checksum.

duration
Wait duration, such as 1s or 500ms, between requests. The default is not to wait.
n
Try a request again up to n times, 5 by default, when it fails with status 429 or 5xx, a network error or a bad checksum, as for archiveorg.

When running alongside the mirrord(1) daemon service, mirror can submit and manage mirror requests in a background queue over a local Unix domain socket.

[-state states [-site site [-prefix prefix [-limit n]]]]
List jobs in the queue, optionally filtering by comma-separated states, site, or URL prefix.
[flags source [destdir]]
(or mirror submit ) Enqueue a mirror job in the background daemon.
id
Show detailed metadata, timings, and error status for a job.
[-f id]
Display logs for a job, optionally streaming live updates with -f.
[id | prefix]
Pause the queue dispatcher, pause an individual job by ID, or pause all queued jobs matching a site or subtree prefix (e.g. example.com or https://example.com/docs/ ).
[id | prefix]
Resume queue processing, resume a specific paused job, or resume all paused jobs matching a site or subtree prefix.
n
Set the maximum number of simultaneous workers.
id | prefix
Cancel an active or queued job, or batch-cancel all jobs matching a site or subtree prefix.
id
Retry a failed or quarantined job.
id | prefix [reason]
Manually isolate an individual job or an entire site/subtree prefix to quarantine.
id | prefix
Return a quarantined job or all quarantined jobs under a site/subtree prefix to the queue.
id
Delete a finished or quarantined job.

The configuration file, ~/.config/mirrortools/config.toml, is in TOML. It can set a default destdir, and, in a section per method, default values for that method's flags, named without the leading ‘-’, and a destdir for that method only:

destdir = "~/mirror"

[groupsio]
email = "me@example.com"
password-file = "~/.config/mirrortools/groupsio-password"

[git]
destdir = "~/git"

[http]
destdir = "~/web"
wait = "1s"

Flags given on the command line override the file. A leading ‘~/’ in a value stands for the home directory.

Most methods mirror each source into a subdirectory of destdir of their own, so they can share the default destdir. The others are given one when they use it: gphotos and icloud mirror into gphotos/account and icloud/account, imap into imap/host, and rsync into host/path, so that the files end up in destdir/host/path with or without a trailing slash. A method's own destdir, or one given on the command line, is used as it is.

The configuration file to read instead of the default one.
If set, the configuration file is $XDG_CONFIG_HOME/mirrortools/config.toml.
The Apple ID password for icloud, if -password-file is not given.
The remote shell rsync runs for a host:path source, instead of ssh(1).

~/.config/mirrortools/config.toml
The configuration file.

The state that lets a later run continue is kept in destdir:

.httpmirror.db, .ftpmirror.db
SQLite databases of every URL or file seen by http and ftp, and whether it is done.
.gphotos-index.json, .icloud-index.json
The items already downloaded by gphotos and icloud.
id/.done
An Internet Archive item that archiveorg has completely downloaded.

mirror exits 0 if everything was mirrored, 1 if anything failed, and 2 for a usage error or an error in the configuration file. A failed run can be repeated: it continues with what is not done yet.

Mirror a directory of a web server:

mirror https://ftp.gnu.org/gnu/hello/ ~/mirror

Mirror an FTP tree, then later pick up new and changed files:

mirror ftp://ftp.example.com/pub/ ~/mirror
mirror -update ftp://ftp.example.com/pub/ ~/mirror

Mirror an archive.org item into the default destdir from the configuration file:

mirror https://archive.org/details/some-item

Mirror every file of a SourceForge project into ~/mirror/fsd-amoeba:

mirror https://sourceforge.net/projects/fsd-amoeba/ ~/mirror

Mirror a web page with the http method although archiveorg would otherwise be picked:

mirror http https://archive.org/about/ ~/mirror

Mirror a mail account:

mirror imap -user me@example.com -password-file ~/.imap-pw \
    imap.example.com ~/mail

git(1), mirrord(1), mirrorq(1), rsync(1), ssh(1), wget(1)

The README of each method, in /usr/share/doc/mirrortools (or /usr/local/share/mirrortools on macOS) and at https://github.com/rpajarola/mirrortools.

Rico Pajarola <rp@servium.ch>

November 3, 2026 Ubuntu