path: root/Duplicati/CommandLine/help.txt

# 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 duplicati.commandline.exe help <topic> for more information.
  General: example, changelog
  Commands: backup, find, restore, delete, compact, test, compare, purge, vacuum
  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, encryption, compression
  Advanced: mail, advanced, returncodes, filter, filter-groups, <option>

http://www.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. 
  
  %MONO%"%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. 
  
  %MONO%"%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). 
  
  %MONO%"%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 ?. 
  
  %MONO%"%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.
  
  %MONO%"%APP_PATH%" restore ftp://me:example.com@ftp.example.com/target "%EXAMPLE_SOURCE_FILE%" --overwrite
    

# =============================================================================
> duplicati.commandline.exe help backup
  
Usage: 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: 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 restore

Usage: restore <storage-URL> ["<filename>"] [<options>]
  
  Restores <filename> to its original destination. If <filename> exists already, <filename> is changed to <filename-timestamp.extension>. To restore all files use "*" or leave empty.

  --overwrite=<boolean>
    Overwrites existing files.
  --restore-path=<string>
    Restores files to <restore-path> instead of their original destination. Top folders are removed if possible.
  --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: 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).
  --allow-full-removal
    Disables the protection against removing the final fileset
  
  
  
# =============================================================================
> duplicati.commandline.exe help compact

Usage: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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 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 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:
  
  %MONO%"%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)
      
# =============================================================================
> 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 warnings
  50 - Backup uploaded some files, but did not finish
  100 - An error occurred
  200 - Invalid commandline arguments found