Command Line Arguments

The default behaviour of the updater if invoked without any CLI arguments is to display the main window if updates are found or message dialogs in case of errors. The following CLI switches are supposed to be used for setting up the updater on the consumer system and customizing it.

Common

`--install`

Typically called only once when the bundled product gets installed. Performs self-registration in current users' autostart and daily runs via Task Scheduler, and extracts the embedded self-updater component. Errors will be logged but the user will not be actively notified. Check the exit code for potential error cases.

Beware of the target directory permissions

If your updater instance gets deployed into a restricted directory (like Program Files) this command needs to be invoked with administrative privileges or some steps requiring write-permissions will fail.

Prerequisite for self-updating feature

The install routine must be run at least once or the self-update feature will not be available.

Beware of parent path changes

If the updater executable is moved to a different location, this command needs to be issued again at least once.

`--no-scheduled-task`

Can be used in conjunction with the --install switch to skip the creation of the Scheduled Task. Useful if you rather wish to invoke the updater via your own mechanism, like a button in your product or whatever event works best for you.

`--no-autostart`

Can be used in conjunction with the --install switch to skip registering in the current users autostart. Useful if you rather wish to invoke the updater via your own mechanism, like a button in your product or whatever event works best for you.

`--override-success-code <code>`

Can be used in conjunction with the --install and --uninstall switch to override the default success exit code with the user-specified value. Useful if the calling process can not be configured to treat any other value than e.g. 0 as a success.

`--uninstall`

Removes the autostart registration and deletes the scheduled task job. The process will exit after these tasks finished successfully or on error.

`--skip-self-update`

Skips the self-update procedure, even if a newer version is available.

`--silent`

Suppresses TaskDialog popups (error messages, "up to date" notices, and UAC prompts). The main update notification window is still shown if updates are found. For a fully headless run that also performs the download and install without any UI, use --silent-update instead.

Check the app exit code for status details.

`--silent-update`

Suppresses any UI, downloads and invokes the latest release found and exits afterwards.

Does nothing if the product is already up to date.

Check exit codes for success or errors

This flag is most useful if you decide to trigger updates directly from your own application.
Make sure to check the exit code to react to possible errors during the update procedure.

`--ignore-busy-state`

Ignores if the user session is busy and displays the main window if updates were found. This flag is only relevant in silent modes (--background, --autostart, --silent, --silent-update), because interactive runs always show the window regardless of session state.

`--ignore-product-in-use`

Skips the product-busy detection gate and shows the update notification dialog immediately, even if the watched product is currently running. Has no effect when productBusyDetection is not configured.

`--log-level <value>`

Alters the default logging level (info) to the provided <value>.

Possible values are: trace, debug, info, warn, err, critical or off.

`--log-to-file <value>`

Logs to the file specified in <value> in addition to the default debug sink.

Ensure the target path is writable

Bear in mind that the log file path needs to be writable for the user executing the updater. It will fail silently if it couldn't write to the specified file. See Logging article for more details.

`--server-url`

Only available in DEBUG builds

This switch is intended to only work with DEBUG builds as it opens up a huge security problem if distributed to production systems. Any malicious process could attempt to direct the updater to a malignant server trying to then download and execute a payload that might further infect the target machine.

Overrides all other Server Discovery methods. Useful to quickly switch to different update configurations while testing the local debug build. The value is ignored in RELEASE builds, if set.

`--channel <value>`

Specifies an alternate update channel to use. This value will be inserted into the server URL template e.g. manufacturer/product/channel which allows the caller to switch between remote updater configurations when invoking the updater manually. This can be used to deliver different update mechanisms for Beta or VIP users etc.

Remarks for v1.8.876 and below

In versions above v1.8.876, there is no validation of this parameter; server-side validation is assumed to be sufficient.

In v1.8.876 and below, the value can be any alphanumeric string excluding the following characters:

'/' (forward slash)
'\' (backslash)
' ' (space)
. (period)
2 (the number 2)

Server-side path validation should still be used with earlier versions of the client.

`--add-header <name=value>`

Allows for adding one or more additional HTTP headers to be added to the update server request. This can be used in conjunction with a backend application server to influence delivery of the remote configuration based on certain custom client parameters.

This parameter can be specified multiple times with different name-value-pairs. For example:

--add-header CustomerId=rZnZzZu9wH --add-header ProcessorVendor=AMD --add-header IsVIP=true

`--ignore-postpone`

Ignores the check if we are in an active postpone period, if specified. Does nothing if there is no active postpone period.

`--purge-postpone`

Deletes the registry-backed postpone data, if present.

`--terminate-process-before-update <handle>`

An optional handle to a process object to terminate before the update starts. See this article for details.

`--local-version <version>`

Overrides the detected local product version if no detection method was specified in either the local or server-provided configuration.

`--force-local-version <version>`

Overrides the detected local product version. This value trumps any product detection method specified in either local or server-provided configuration.

`--strict-verification`

Activates a client-side hardened verification mode. Has three effects:

Checksum required — if the selected release does not provide a checksum field in the remote configuration, the update is rejected after download with exit code 116.
Server cannot downgrade security — the signature verification settings (signatureVerificationMode, signaturePolicy, signatureStrategy, signatureConfig) from the server's shared section are ignored. Only values already present in the local configuration or baked into the build apply.
Minimum security floor — if the merged signatureVerificationMode is WhenPresent or Disabled, it is silently upgraded to Required; if signaturePolicy is Relaxed, it is upgraded to Strict.

See Signature & Manifest Verification for full details on the verification pipeline.

Internal

Beware of altering

The following arguments are set or removed by other common commands and should not be altered by the user.

`--autostart`

Performs tasks on user logon like checking self-integrity and searching for updates.

`--background`

Tells the updater it's run by Task Scheduler. It will not display any UI except when an update has been found. Errors will be logged but the user will not be actively notified.

`--temporary`

Tells the updater it's run as a temporary child process to avoid blocking an in-progress setup procedure by locking the origin file. If this flag is present, certain commands (like --install) are ignored.

Incompatible with silent-mode flags

Combining --temporary with any silent-mode flag (--silent, --background, --autostart, or --silent-update) is not supported. The updater will abort at startup and exit with code 112.

Self-Updater

The following parameters are passed from the main updater process to the self-updater module.

They can not be altered by the user.

Forwarded common arguments

--silent and --log-level are always forwarded from the parent process and apply identically inside the self-updater module.

`--pid`

The Process ID of the parent updater process that invoked the self-update module.

`--url`

The primary download URL of the latest updater executable. Redirects are supported.

`--path`

The absolute path to the local updater executable that will be replaced.

`--checksum <value>`

The expected hash digest (lowercase hex string) of the downloaded updater binary. The self-updater verifies this before swapping the binary into place. Populated from the latestChecksum field in the remote configuration. Omitted when no checksum was provided server-side.

`--checksum-alg <value>`

The hashing algorithm to use when verifying --checksum. Possible values: SHA256, SHA1. Defaults to SHA256 when omitted.

MD5 not supported by the self-updater

Although the main updater supports MD5 for release checksums, the self-updater module only accepts SHA256 and SHA1. Specifying MD5 for latestChecksum in the remote configuration will cause self-updater verification to fail.

`--mirror-url <url>`

A fallback download URL used if the primary --url fails. May be specified multiple times, once per mirror. Populated from the latestMirrorUrls array in the remote configuration.

`--proxy <url>`

An explicit HTTP proxy URL (e.g. http://proxy.corp:8080) forwarded from the network configuration. Only present when a proxy is explicitly configured.

`--no-proxy`

Forces a direct connection for the self-updater download, overriding any environment-variable proxy. Forwarded when the network configuration sets ProxyMode::None.

`--doh-url <url>`

A DNS-over-HTTPS resolver URL forwarded from the network configuration.