CLI

Usage

s3mirror [-c FILE] [-w N] [--no-delete] [-q] [-d] [-l FILE]
s3mirror -c FILE --show-config
s3mirror --version

s3mirror takes no positional arguments; everything it mirrors is in the config file. Each run mirrors every source bucket that isn’t excluded, and there are no flags to pick buckets, prefixes or objects.

Running

Flag	Default	Description
-c--config FILE	None	Config file to read, .yaml, .yml or .json. Without it, s3mirror runs on its built-in placeholders, which fail the connection check, so in practice every run needs it.
-w--workers N	max_workers	Objects to copy, and later delete, at the same time, overriding max_workers (20 unless the config sets it). Must be a whole number of at least 1.
--no-delete	None	Don't delete destination objects the source doesn't have, whatever delete_extraneous says. The run copies and reports, nothing more.

Output

Flag	Default	Description
-q--quiet	None	Print only error lines on the console. Wins over --debug when both are given.
-d--debug	None	Print everything on the console, each line prefixed with its level: every listing, comparison, copy and deletion. With --log-file, keeps the console at debug instead of errors only.
-l--log-file FILE	None	Append a full debug log, with timestamps, to this file, and print only error lines on the console unless --debug is also given. The directory must already exist.

These three only change where output goes and how much of it there is. Logging has the console level for every combination and the format of each destination.

Other

Flag	Default	Description
--show-config	None	Print the configuration the run would use as JSON, after --workers and --no-delete are applied and with the keys redacted, then exit 0 without connecting. A config value s3mirror can't use is reported as an error instead, with exit code 1.
--version	None	Print the version, such as S3 Mirror v1.1.0, then exit 0.
-h--help	None	Print usage and the flags, then exit 0.

Flags and the config

Only two settings can be changed from the command line, and both win over the config for that run: --workers sets performance.max_workers, and --no-delete sets sync.delete_extraneous to false. Everything else, including the endpoints and exclude_buckets, comes from the file.

Errors

An unknown flag, a missing value or a --workers value that isn’t a positive whole number prints usage and the problem to standard error and exits 2, before anything else happens:

Output

usage: s3mirror [-h] [-c FILE] [-q] [-d] [-l FILE] [-w N] [--no-delete]
                [--show-config] [--version]
s3mirror: error: argument -w/--workers: must be greater than zero

Exit codes has every code s3mirror exits with.

--help

Output

usage: s3mirror [-h] [-c FILE] [-q] [-d] [-l FILE] [-w N] [--no-delete]
                [--show-config] [--version]

S3 Bucket Mirror - Professional bucket synchronization

options:
  -h, --help           show this help message and exit
  -c, --config FILE    Configuration file path (.yaml, .yml or .json)
  -q, --quiet          Quiet mode - only errors (for cron)
  -d, --debug          Debug mode - verbose output
  -l, --log-file FILE  Log to file (console shows only errors unless --debug
                       specified)
  -w, --workers N      Number of parallel workers (default: max_workers, 20 if
                       unset)
  --no-delete          Don't delete extraneous files from destination
  --show-config        Display configuration and exit
  --version            show program's version number and exit

Examples:
  # Normal operation (console output)
  s3mirror --config /etc/s3mirror.yaml

  # Try it first without deleting anything, showing every decision
  s3mirror --config /etc/s3mirror.yaml --no-delete --debug

  # Silent mode for cron
  s3mirror --config /etc/s3mirror.yaml --quiet

  # Log to file (only errors on the console, everything in the file)
  s3mirror --config /etc/s3mirror.yaml --log-file /var/log/s3mirror.log

  # Log to file with debug console output too
  s3mirror --config /etc/s3mirror.yaml --debug --log-file /var/log/s3mirror.log

From a checkout, or in the container, the program name in the help is s3mirror.py.