duplicati/Duplicati/CommandLine/CLI/help.txt
2025-05-21 12:50:31 +02:00

674 lines
32 KiB
Text

# This file is the help for the Duplicati Command Line Client. It shows what
# commands the CLI understands and what the outputs are. Sometimes we used
# placeholders for options. In that case descriptions are taken directly from
# the modules. Sometimes we described options here. The reason for that is,
# that we found the new description much better but did not want to create a
# need for translation as many options are described in the UI as well and
# they are translated there.
# =============================================================================
> duplicati.commandline.exe
> duplicati.commandline.exe help
See %CLI_EXE% help <topic> for more information.
General: example, changelog
Commands: backup, find, restore, delete, compact, test, compare, purge, vacuum
Searching: list-filesets, list-folder-contents, list-file-versions, search-files
Repair: repair, affected, list-broken-files, purge-broken-files
Debug: debug, logging, create-report, test-filters, system-info, send-mail
Targets: %BACKENDS%
Modules: %ENCRYPTIONMODULES%, %COMPRESSIONMODULES%, %GENERICMODULES%
Formats: date, time, size, decimal, encryption, compression
Advanced: mail, advanced, returncodes, filter, filter-groups, <option>
Secrets: password, secret, <provider>
https://duplicati.com/ Version: %VERSION%
# =============================================================================
> duplicati.commandline.exe help changelog
Show the last changes to Duplicati
==================================
Duplicati updates automatically when a newer version is available. The following command will show a list of versions and changes.
"%APP_PATH%" changelog
# =============================================================================
> duplicati.commandline.exe help system-info
> duplicati.commandline.exe help systeminfo
Show system information as seen by Duplicati
============================================
Issue the following command to see a variety of system information relevant to Duplicati.
"%APP_PATH%" system-info
# =============================================================================
> duplicati.commandline.exe help example
> duplicati.commandline.exe help examples
Make an encrypted backup
========================
The following command will make an encrypted backup and store it on an FTP server. As no passphrase is specified, the user is prompted for a password. The upload speed is throttled to 500kB/s. Backups older than one month are considered old. Old backups are deleted automatically. The maximum file size is limited to 50MB (default).
"%APP_PATH%" backup ftp://me:example.com@ftp.example.com/target "%EXAMPLE_SOURCE_PATH%" --throttle=500kB
Search for files in a backup
============================
The backup can be searched for specific files. The following command returns all files "%EXAMPLE_SOURCE_FILE%" of the last backup. File names can also contain the wildcards * and ?.
"%APP_PATH%" find ftp://me:example.com@ftp.example.com/target "%EXAMPLE_SOURCE_FILE%"
Restore a specific file
=======================
The following command will restore "%EXAMPLE_SOURCE_FILE%" from the backup in the latest version to its original destination and overwrite an existing file.
"%APP_PATH%" restore ftp://me:example.com@ftp.example.com/target "%EXAMPLE_SOURCE_FILE%" --overwrite
# =============================================================================
> duplicati.commandline.exe help backup
Usage: %CLI_EXE% backup <storage-URL> "<source-path>" [<options>]
Makes a backup of <source-path> and stores it in <storage-URL>. The format for <storage-URL> is
protocol://username:password@hostname:port/path?backend_option1=value1&backend_option2=value2.
Multiple source paths can be specified if they are separated by a space.
%IF_WINDOWS%
On Windows clients, there are two special ways to specify the drive for files to back up. These two methods may help to back up sources on removable drives, whose drive letters may not be reliable.
1. The first is to specify the the drive using the volume guid, for example "%EXAMPLE_VOLUME_GUID_SOURCE_PATH%". In this case, the drive letter of the drive with the matching volume guid will be substituted to find the actual source path. The volume guid remains constant no matter which drive letter the drive is mounted to. These volume guids can be found using the 'mountvol' command line tool, or picked from the list below:
%KNOWN_DRIVES_AND_VOLUMES%
2. The second is to use a wildcard (* or ?) in place of the drive name, for example "%EXAMPLE_WILDCARD_DRIVE_SOURCE_PATH%". In this case, the given source path will be backed up from all drives on which the path exists. This can be useful when backing up sources which may be present on multiple drives with different volume guids. When using --allow-missing-source, the backup will succeed as long as at least one path matches the wildcarded path.
%END_IF_WINDOWS%
<username> must not contain : and <password> must not contain @. If they do, specify username and password using --auth-username and --auth-password, or url-encode them.
--auth-password=<string>
The password that is required to authenticate with the server the backup is stored on.
--auth-username=<string>
The username that is required to authenticate with the server the backup is stored on.
--no-encryption=<boolean>
Use this to make an unencrypted backup.
--passphrase
This is the passphrase that is used to encrypt all data before it is uploaded. If an empty passphrase is specified, the backup will not be encrypted. This is the same as using --no-encryption.
--prefix=<string>
Replaces the default "duplicati" with <string> in the file names of the backup files. It is required to specify different prefixes if multiple backups are stored in the same target folder.
# =============================================================================
> duplicati.commandline.exe help find
> duplicati.commandline.exe help list
Usage: %CLI_EXE% find <storage-URL> ["<filename>"] [<options>]
Finds specific files in specific backups. If <filename> is specified, all occurrences of <filename> in the backup are listed. <filename> can contain * and ? as wildcards. File names in [brackets] are interpreted as regular expression. Latest backup is searched by default. If entire path is specified, all available versions of the file are listed. If no <filename> is specified, a list of all available backups is shown.
--time=<time>
Shows what the files looked like at a specific time. Absolute and relative times can be specified.
--version=<int>
Shows what the files looked like in a specific backup. If no version is specified the latest backup (version=0) will be used. If nothing is found, older backups will be searched automatically.
--include=<string>
Reduces the list of files in a backup to those that match the provided string. This is applied before the search is executed.
--exclude=<string>
Removes matching files from the list of files in a backup. This is applied before the search is executed.
--all-versions=<boolean>
Searches in all backup sets, instead of just searching the latest
# =============================================================================
> duplicati.commandline.exe help list-filesets
Usage: %CLI_EXE% list-filesets <storage-URL> [<options>]
Lists all filesets found and some basic metadata
--no-local-db=<boolean>
Ignores a local database if one exists, and lists the remote folder contents
# =============================================================================
> duplicati.commandline.exe help list-folder-content
> duplicati.commandline.exe help list-folder-contents
Usage: %CLI_EXE% list-folder-content <storage-URL> ["folder"] [<options>]
Lists all entries in the given folders for the chosen fileset.
Only a single fileset can be selected.
If no fileset is specified, the latest fileset is picked.
If no folder is given, the root folders are returned.
--time=<time>
Choose the fileset that matches the timestamp given
--version=<int>
Choose the fileset that matches the version given
# =============================================================================
> duplicati.commandline.exe help list-file-versions
Usage: %CLI_EXE% list-file-versions <storage-URL> ["path"] [<options>]
List all versions of the given paths in the versions.
Paths are case-sensitive.
--time=<time>
Looks at all versions older than the given time.
--version=<int>
Looks at only the versions given.
--all-versions=<boolean>
Searches in all backup sets (this is the default)
# =============================================================================
> duplicati.commandline.exe help search-files
> duplicati.commandline.exe help search-entries
> duplicati.commandline.exe help search
Usage: %CLI_EXE% search <storage-URL> ["folder"] [<options>]
Finds paths that matches the expression.
If folders are supplied, only those folders and subfolders are searched.
Folder paths are case-sensitive, filters are case-insensitive.
--include=<string>
Supplies a filter that the items must match.
--exclude=<string>
Supplies a filter that will exclude items if they match.
--time=<time>
Looks at all versions older than the given time. Absolute and relative times can be specified.
--version=<int>
Looks at only the versions given. If no version is specified the latest backup (version=0) will be used.
--all-versions=<boolean>
Searches in all backup sets (this is the default)
# =============================================================================
> duplicati.commandline.exe help restore
Usage: %CLI_EXE% restore <storage-URL> ["<filename>"] [<options>]
Restores <filename> to its original destination. If <filename> exists already and --overwrite=false is set, then <filename> is changed to <filename-timestamp.extension>. To restore all files use "*" or leave empty.
--overwrite=<boolean>
Overwrites existing files.
--restore-legacy=<bool>
Use this option to use the legacy restore method. The legacy restore method is slower than the new method, but may be more reliable in some cases. The default is false, which means that the new restore method is used.
--restore-path=<string>
Restores files to <restore-path> instead of their original destination. Top folders are removed if possible.
--restore-permissions=<bool>
By default permissions are not restored as they might prevent you from accessing your files. Use this option to restore the permissions as well.
--skip-metadata=<bool>
Use this option to skip the metadata restore. The default is false, which means that metadata is restored.
--time=<time>
Restore files that are older than the specified time.
--version=<int>
Restore files from a specific backup.
# =============================================================================
> duplicati.commandline.exe help delete
Usage: %CLI_EXE% delete <storage-URL> [<options>]
Marks old data deleted and removes outdated dlist files. A backup is deleted when it is older than <keep-time> or when there are more newer versions than <keep-versions>. Data is considered old, when it is not required from any existing backup anymore.
--dry-run
Performs the operation, but does not write changes to the local database or the remote storage.
--keep-time=<time>
Marks data outdated that is older than <time>.
--keep-versions=<int>
Marks data outdated that is older than <int> versions.
--version=<int>
Deletes all files that belong to the specified version(s).
--retention-policy=<policy>
Deletes all files that are not preserved by the retention policy.
--allow-full-removal
Disables the protection against removing the final fileset.
# =============================================================================
> duplicati.commandline.exe help compact
Usage: %CLI_EXE% compact <storage-URL> [<options>]
Old data is not deleted immediately as in most cases only small parts of a dblock file are old data. When the amount of old data in a dblock file grows it might be worth to replace it. This is especially the case when the number of dblock files and thus the required storage space can be reduced. When backups are frequently made and only few files have changed, the uploaded dblock files are small. At some point it might make sense to replace a large number of small files with one large file. This is what compacting does.
--small-file-max-count=<int>
The maximum allowed number of small files.
--small-file-size=<int>
Files smaller than this size are considered to be small and will be compacted with other small files as soon as there are <small-file-max-count> of them. --small-file-size=20 means 20% of <dblock-size>.
--threshold=<percent_value>
The amount of old data that a dblock file can contain before it is considered to be replaced.
# =============================================================================
> duplicati.commandline.exe help compare
Usage: %CLI_EXE% compare <storage-URL> [<base-version>] [<compare-to>] [<options>]
Compares two backups and shows differences. If no versions are given, changes are shown between the two latest backups. The versions can either be timestamps or backup version numbers. If only one version is given, the most recent backup is compared to that version.
--full-result
Shows all changes
--include=<filter>
Adds an include filter (for verbose output)
--exclude=<filter>
Adds an exclude filter (for verbose output)
# =============================================================================
> duplicati.commandline.exe help create-report
Usage: %CLI_EXE% create-report <storage-URL> <output-file> [<options>]
Analyses the backup and prepares a report with anonymous information. This report can be sent to the developers for a better analysis in case something went wrong.
# =============================================================================
> duplicati.commandline.exe help repair
Usage: %CLI_EXE% repair <storage-URL> [<options>]
Tries to repair the backup. If no local db is found or the db is empty, the db is re-created with data from the storage. If the db is in place but the remote storage is corrupt, the remote storage gets repaired with local data (if available).
# =============================================================================
> duplicati.commandline.exe help purge
Usage: %CLI_EXE% purge <storage-URL> <filenames> [<options>]
Purges (removes) files from remote backup data. This command can either take a list of filenames or use the filters to choose which files to purge. The purge process creates new filesets on the remote destination with the purged files removed, and will start the compacting process after a purge. By default, the matching files are purged in all versions, but this can be limited by choosing one or more versions. To test what will happen, use the --dry-run flag.
--dry-run
Performs the operation, but does not write changes to the local database or the remote storage
--version=<int>
Selects specific versions to purge from, multiple versions can be specified with commas
--time=<time>
Selects a specific version to purge from
--no-auto-compact
Performs a compact process after purging files
--include=<filter>
Selects files to purge, using filter syntax
# =============================================================================
> duplicati.commandline.exe help broken
> duplicati.commandline.exe help broken-files
> duplicati.commandline.exe help list-broken-files
> duplicati.commandline.exe help purge-broken-files
Usage: %CLI_EXE% list-broken-files <storage-URL> [<options>]
Checks the database for missing data that cause files not not be restoreable. Files can become unrestoreable if remote data files are defect or missing. Use the list-broken-files command to see what the purge-broken-files command will remove.
Usage: %CLI_EXE% purge-broken-files <storage-URL> [<options>]
Removes all files from the database and remote storage that are no longer restoreable. Use this operation with caution, and only if you cannot recover the missing remote files, but want to continue a backup. Even with missing remote files, it may be possible to restore parts of the files that will be removed with this command.
--dry-run
Performs the operation, but does not write changes to the local database or the remote storage
# =============================================================================
> duplicati.commandline.exe help test
> duplicati.commandline.exe help verify
Usage: %CLI_EXE% test <storage-URL> <samples> [<options>]
Verifies integrity of a backup. A random sample of dlist, dindex, dblock files is downloaded, decrypted and the content is checked against recorded size values and data hashes. <samples> specifies the number of samples to be tested. If "all” is specified, all files in the backup will be tested. This is a rolling check, i.e. when executed another time different samples are verified than in the first run. A sample consists of 1 dlist, 1 dindex, 1 dblock.
--time=<time>
Checks samples from a specific time.
--version=<int>
Checks samples from specific versions. Delimiters are , -
--full-remote-verification
Checks the internal structure of each file instead of just verifying the file hash
# =============================================================================
> duplicati.commandline.exe help test-filters
> duplicati.commandline.exe help test-filter
Usage: %CLI_EXE% test-filters <source-path> [<options>]
Scans the source files and tests against the filters specified, the console output shows which files and folders are examined and the result.
# =============================================================================
> duplicati.commandline.exe help affected
Usage: %CLI_EXE% affected <storage-URL> <remote-filename> [<remote-filenames>] [<options>]
Returns a report explaining what backup sets and files are affected by a remote file. You can use this option to see what source files are affected if one or more remote files are damaged or deleted. Notes that this command requires a local database to be present, if the database is not found automatically, you can set --dbpath to point to the database to use.
# =============================================================================
> duplicati.commandline.exe help vacuum
Usage: %CLI_EXE% vacuum <storage-URL> [<options>]
Rebuilds the local database, repacking it into a minimal amount of disk space.
# =============================================================================
> duplicati.commandline.exe help debug
> duplicati.commandline.exe help logging
Duplicati provides information for debugging and logging purposes. By default, all debugging and logging is turned off.
--debug-output
Error messages are more verbose.
--debug-retry-errors
If something needs to be retried (e.g. upload failed) this will cause an entry in the log file.
--log-file = <path>
The path to the log file e.g. "D:\duplicati\log.txt".
--log-file-log-level = Profiling | Verbose | Information | Warning | Error
Specifies the log level to use for the log file.
--console-log-level = Profiling | Verbose | Information | Warning | Error
Specifies the log level to use for the console log.
# =============================================================================
> duplicati.commandline.exe help encryption
> duplicati.commandline.exe help compression
Duplicati offers various options for the used compression and encryption modules.
--encryption-module = %ENCRYPTIONMODULES%
The encryption module that is used to encrypt backups. Default is %DEFAULTENCRYPTIONMODULE%.
--compression-module = %COMPRESSIONMODULES%
The compression module that is used. Default is %DEFAULTCOMPRESSIONMODULE%.
--enable-module = %GENERICMODULES%
Enable a built-in generic module that is not enabled by default
--disable-module = %GENERICMODULES%
Disable a built-in generic module that is enabled by default
%OPTION:passphrase%
%OPTION:no-encryption%
# =============================================================================
> duplicati.commandline.exe help gpg
Duplicati is shipped with an interface to GNU Privacy Guard. It requires that the gpg executable is available on the system. On Windows it is assumed that this is in the default installation folder under program files, under Linux and OSX it is assumed that the program is available via the PATH environment variable. It is possible to supply the path to GPG using the --gpg-program-path switch.
Options:
%MODULEOPTIONS%
# =============================================================================
> duplicati.commandline.exe help file
Duplicati can use the local file system to store backups. The following target URL formats can be used:
file://hostname/folder%20for%20backup
file://\\server\folder%20for%20backup (UNC path)
"C:\folder for backup"
file://c:\folder%20for%20backup (Windows)
file:///usr/pub/folder%20for%20backup (Linux)
Options:
%MODULEOPTIONS%
# =============================================================================
> duplicati.commandline.exe help tahoe
> duplicati.commandline.exe help tahoelafs
Duplicati can use the TahoeLAFS to store backups. The following target URL format is used:
tahoe://hostname:port/uri/$DIRCAP
Options:
%MODULEOPTIONS%
# =============================================================================
> duplicati.commandline.exe help ftp
Duplicati can use FTP servers to store backups. The following target URL formats can be used:
ftp://hostname/folder
Options:
%MODULEOPTIONS%
# =============================================================================
> duplicati.commandline.exe help ssh
Duplicati can use SSH servers to store backups. The following target URL formats can be used:
ssh://hostname/folder
Options:
%MODULEOPTIONS%
# =============================================================================
> duplicati.commandline.exe help webdav
Duplicati can use WebDAV servers to store backups. The following target URL formats can be used:
webdav://hostname/folder"
Options:
%MODULEOPTIONS%
# =============================================================================
> duplicati.commandline.exe help s3
Duplicati can use S3-compatible servers to store backups. The following target URL format is used:
s3://bucketname/prefix
Options:
%MODULEOPTIONS%
# =============================================================================
> duplicati.commandline.exe help azure
Duplicati can use Azure blob storage to store backups. The following target URL format is used:
azure://bucketname
Options:
%MODULEOPTIONS%
# =============================================================================
> duplicati.commandline.exe help onedrive
Duplicati can use Microsoft Onedrive to store backups. The following target URL format is used:
onedrive://folder/subfolder
Options:
%MODULEOPTIONS%
# =============================================================================
> duplicati.commandline.exe help date
> duplicati.commandline.exe help time
Duplicati supports absolute and relative dates and times:
now --> The current time
1234567890 --> A timestamp, seconds since 1970.
"2009-03-26T08:30:00+01:00" --> An absolute date and time. You can also use the local date and time format of your system like e.g. "01-14-2000" or "01 jan. 2004".
Y, M, D, W, h, m, s --> Relative date and time: year, month, day, week, hour, minute, second. Example: 2M10D5h is now + 2 months + 10 days + 5 hours.
# =============================================================================
> duplicati.commandline.exe help size
Whenever a size is required, you can use any of the following suffixes:
B - Bytes
kB - Kilobytes
MB - Megabytes
GB - Gigabytes
For speed limits, use the same format. If you enter 1MB this will be 1MB/sec.
# =============================================================================
> duplicati.commandline.exe help decimal
For entering decimal values you must use the English notation, with a period as decimal separator:
0.1
12.34
# =============================================================================
> duplicati.commandline.exe help filter
> duplicati.commandline.exe help filters
Duplicati can apply globbing and regex filter rules to backup and restore specific files only. Globbing filters can be used in file names. To specify a regex filter put the filter in [brackets].
Globbing: *.txt
Regex: [.*test\.txt]
--include=<filter>
Adds an include filter
--exclude=<filter>
Adds an exclude filter
Duplicati also has several built-in groups of filters, which include commonly excluded files and folders for different operating systems. These can be specified by putting the name of the group in {curly brackets}.
%FILTER_GROUPS_SHORT%
For more details about these groups, including exactly what files they cover, see 'filter-groups'.
Inside scripts and the commandline --parameters-file, where multiple filters are supplied with a single option, filters must be prefixed with either a plus (+) or a (-), for include and exclude respectively. Example:
+*.txt%PATH_SEPARATOR%-[.*\.xyz]%PATH_SEPARATOR%+*
# =============================================================================
> duplicati.commandline.exe help filter-group
> duplicati.commandline.exe help filter-groups
Duplicati has several built-in groups of filters, which include commonly excluded files and folders for different operating systems. These sets can be specified via the --include/--exclude parameter by putting their name in {curly brackets}.
%FILTER_GROUPS_LONG%
# =============================================================================
> duplicati.commandline.exe help mail
> duplicati.commandline.exe help email
> duplicati.commandline.exe help send-mail
Duplicati can send email notifications after each operation. Use the send-mail command to test this:
"%APP_PATH%" send-mail --send-mail-to=<email-address>
--send-mail-to=<email-address>
Send an email to <email-address> after a backup. Valid formats are "Name <test@example.com>, Other <test2@example.com>, test3@example.com". Multiple addresses must be separated with a comma.
--send-mail-from=<email-address>
This is the sender address of the email that is sent.
--send-mail-subject=<subject>
This is the subject line of the email that is sent. E.g. this can be "Duplicati %OPERATIONNAME% Report"
--send-mail-body=<body>
The content of the email message. This should contain "%RESULT%".
--send-mail-url=<smtp-url>
A URL to connect to an SMTP server to send out an email. Example: "tls://smtp.example.com:587", "smtps://smtp.example.com:465" or "smtp://smtp.example.com:25"
--send-mail-username=<username>
Required username to authenticate with SMTP server.
--send-mail-password=<password>
Required password to authenticate with SMTP server.
--send-mail-level=<level>
When email messages are sent: "Success", "Warning", "Error", "Fatal", "All" are possible.
--send-mail-any-operation=true
Also send emails after other operations like restore etc.
Allowed placeholders are:
%PARSEDRESULT%
The parsed result op the operation: Success, Warning, Error
%RESULT%
When used in the body, this is the result/log of the backup,
When used in the subject line, this is the same as %PARSEDRESULT%
%OPERATIONNAME%
The name of the operation, usually "backup", but could also be "restore" etc.
%REMOTEURL%
The backend url
%LOCALPATH%
The path to the local folders involved (i.e. the folders being backed up)
%machine-id%
The assigned unique random identifier for the current machine, can be overridden with --machine-id
%backup-id%
The assigned id for the backup, can be overridden with --backup-id
%backup-name%
The name of the backup, can be overridden with --backup-name
%machine-name%
The name of the machine, can be overridden with --machine-name
# =============================================================================
> duplicati.commandline.exe help advanced
> duplicati.commandline.exe help option
> duplicati.commandline.exe help options
Duplicati offers more options than listed in the other topics. Those additional options should only be used with care. For normal operation none of them should ever be required. Here is a complete list of options supported by Duplicati:
%MAINOPTIONS%
# =============================================================================
> duplicati.commandline.exe help returncodes
> duplicati.commandline.exe help exitcodes
> duplicati.commandline.exe help statuscodes
> duplicati.commandline.exe help errorlevel
Duplicati reports the following return/exit codes:
0 - Success
1 - Successful operation, but no files were changed
2 - Successful operation, but with warning(s)
3 - For backup: finished with error(s), for test: error(s) found on the backend
50 - Backup uploaded some files, but did not finish
100 - An error occurred
200 - Invalid commandline arguments found
# =============================================================================
> duplicati.commandline.exe help secret
> duplicati.commandline.exe help secrets
> duplicati.commandline.exe help secret-provider
Duplicati supports reading secrets from an external secret provider.
The setup is done by adding an option:
--secret-provider=<config>
This setup will make Duplicati replace all values starting with a $-symbol, using the secret provider.
As an example, if the setting is:
--passphrase=$backup-passhrase
Duplicati will use the secret provider to fetch the secret for the key "backup-passphrase", and replace the value before starting the operation. If the value is not found the operation will fail.
Replacing can also be done inside the backend urls, such that a backend url could be:
s3://?aws-access-key-id=$awsid&aws-secret-access-key=$awskey
Here the values "awsid" and "awskey" would be fetched from the secret provider and replaced verbatim in the url (make sure to url encode the secrets in the provider).
To support more robust parsing, it is also possible to change the pattern from the default "$":
--secret-provider-pattern=!secret{}
This would extract keys inside that pattern, such as extracting "key name" from "!secret{key name}".
For providers that return a set of secrets, the key lookup is default case insensitive.
For providers that require a request per secret, the lookup is case-sensitive.
The following secret providers are supported:
%SECRETPROVIDERS%
# =============================================================================
> duplicati.commandline.exe help password
> duplicati.commandline.exe help passwords
You can provide the encryption passphrase and login credentials from the commandline, but this will make them visible to other users on the system that can list processes.
You can instead use the environment variables:
- PASSPHRASE, mapped to --passphrase
- AUTH_USERNAME, mapped to --auth-username
- AUTH_PASSWORD, mapped to --auth-password
Note that if the argument is given on the commandline, the environment variable is ignored.
You may also use the --parameters-file option to store the secrets, so they cannot be seen as environment variables. Be sure that you secure the file with appropriate permissions.
If you prefer to not store secrets on disk, see the secret providers:
"%APP_PATH%" help secret-provider