Setup.exe command line syntax

Most of InstallMate's behavior is determined by the contents of your project, which are stored in the installation database that is included in the distribution package. However, InstallMate also recognizes a number of command line options that modify its default behavior.

Command line syntax

InstallMate's Setup.exe program (including all self-extracting executables built with InstallMate) uses the following command line syntax. Parts between [brackets] are optional; ellipsis "..." indicate parts that may be repeated.

[path\]Setup.exe [runmode] [options...] [var=value...] [$comp=state...] [@response.txt]
Part Description
[path\]Setup.exe Specifies the Setup program's file name or fully qualified path. In actual usage, this may be Setup.exe or any other name that you assigned to the Single Exe distribution package on the Build page.
runmode Optional run mode. If you do not specify a run mode, Setup will run according to the rules set out under Run mode options, below. Run modes may start with / or - and are not case-sensitive. Therefore, -install, /install, and /INSTALL all have the same effect.
options... Specifies zero or more installation options. Options may start with / or - and are not case-sensitive. Therefore, -q, /q, and /Q all have the same effect. Options are processed from left to right, so if you specify conflicting options, the rightmost one "wins".
var=value...

Specifies zero or more var=value pairs that allow you to set the value of symbolic variables from the command line.

Any values set on the command line override the values of the corresponding variables from the installation script. If a variable doesn't exist in the installation script, it is automatically created.

Note: If value contains spaces or special characters such as '<' and '>', you should quote the entire option as in "var=value". This allows you to use other symbolic variables as part of the value specification, for example "INSTALLDIR=<ProgramFilesFolder>\<ProductName>".

$comp=state...

[InstallMate 9.2 and later] Specifies zero or more $comp=state pairs that allow you to set the selection state of components in your installer.

Any $comp=state instructions are evaluated during the InitComponents standard action (typically at the start of the DoFirstInstall action sequence) and override both the Initial state and the If condition true fields of the component, and any states that are loaded from the previously installed instance of the same product.

  • The comp portion (without the leading '$') must specify the internal Name field of the component;
  • The state portion must be an integer from 0 to 5 with the following meaning:
State Description
0 Set default state. This evaluates the Initial state and the If condition true fields of the component in conjunction with its Condition (if any), and assigns the resulting state. This option allows you to restore a component to its default selection, even if there is a currently installed version of the product that used a different selection state.
1 Set component state to Hidden
2 Set component state to Disabled
3 Set component state to Not selected
4 Set component state to Selected
5 Set component state to Always selected

Note: $comp=state options are evaluated from left to right on the command line. For best results, we recommend that you specify higher-level components before their children if you want to change their selection state, because the selection state of a parent component may affect the available selection states of its children.

@response.txt

Use response.txt as a response file for further command line arguments.

A response file is a plain text file (encoded in the current ANSI code page, or UTF-8 with a leading BOM, or UTF-16 with its leading BOM) that contains one or more command line arguments separated by any combination of spaces, tabs, or newlines.

The syntax of the arguments in the response file is similar to the normal command line usage; in particular, any arguments that contain internal spaces must be "quoted". However, response files differ from normal command line syntax in the following ways:

  • Input and output redirections ('<' and '>') and pipes ('|') have no effect because the command line processor (CMD.EXE, TCC.EXE, or similar) never sees the response file contents.
  • As a corollary, inside a response file you can refer to symbolic variables with unquoted <varname> syntax, for example INSTALLDIR=<ProgramFilesFolder>\<ProductName>
  • Environment variable references such as %APPDATA% are expanded inside a response file as they would be on the command line proper. To pass the literal string %APPDATA% as an argument to the program, you must use single 'quotes', for example '%APPDATA%'; double %% signs as on the command line do not prevent expansion. Only simple expansion is performed; CMD.EXE features such as %varname:str1=str2% (string substitution) and others are not supported.
  • No other command line processor features apply.

Response files may be nested and will be processed if and when they appear on the command line and in other response files, and the same left-to-right processing rules apply when conflicting arguments are encountered (i.e., the rightmost argument "wins").

Internal comment lines

[InstallMate 9.39 and later] Response files may contain internal comment lines for documentation purposes; the contents of a comment line are ignored by the program.

Comment lines must start with '#' in the first column of the line and extend up to and including the next line break or the end of the file, whichever comes first. '#' characters that appear after the first column of a line are not treated as comments and are considered part of the argument in which they appear. Some examples:

# This is a comment line
 # But this is not (starts in column 2)
"# Nor is this"
/nor#this
nor#this.txt
# But this is another comment

Run mode options

The InstallMate program is a single executable that acts both as installer and uninstaller. Normally, InstallMate determines automatically in which capacity it should run. However, there may be occasions where you want to deviate from the usual rules, for example to force a registration run in order to repair a damaged installation.

The current run mode is available and may be set through the TsuRunMode variable. However, changing the run mode after InstallMate has started should be done with great care or it may lead to unpredictable results.

New installation
A new installation is any installer that runs from the self-extracting package that is created by InstallMate Builder's Build command, even if the same product is already installed on the target system.
Existing installation
An existing installation is one where Setup.exe runs from its installed location on the target system. See Setup installation location for details.

InstallMate recognizes the following run mode options:

Option Description
(none)

Initial run mode if no other run mode options are specified on the command line.

  • If this is a new installation, then the installer automatically switches to Installer mode (see next).
  • Else if Setup is running interactively, the user is prompted to select the desired run mode.
  • Else Setup is running in silent mode and the installer fails with exit code 7 (Invalid run mode; see Exit codes below).

Corresponds to TsuRunMode value 0.

/install
/install:installfolder

Force Installer mode. The second form allows you to specify an installation folder. It is equivalent to /install followed by INSTALLDIR=installfolder.

You can use absolute paths such as C:\MyApp or symbolic variables such as <ProgramFilesFolder>\MyApp for installfolder. Be sure to quote the entire option if installfolder contains spaces or symbolic variables, or Windows will misinterpret the command line.

Note: Because you are essentially assigning a new value to the INSTALLDIR folder alias, installfolder should not refer to <INSTALLDIR> either directly or indirectly to avoid infinite recursion.

Corresponds to TsuRunMode value 1.

/register

Force Registrar mode.

In Registrar mode, the installer only performs post-boot file registration. This is required if one or more files were in use during the original installation. In that case, Setup automatically registers itself to run in Registrar mode after the next system reboot.

Note: This option is ignored by new installations, which always run as Installer.

Corresponds to TsuRunMode value 3.

/remove

Force Uninstaller mode.

Completely removes your application from the customer's computer.

Note: This option is ignored by new installations, which always run as Installer.

Corresponds to TsuRunMode value 2.

/repair

Force Repair mode.

Re-installs your application unchanged, usually to repair a damaged installation. This requires access to the installer's original distribution media.

Note: This option is ignored by new installations, which always run as Installer.

Corresponds to TsuRunMode value 4.

/resume

Force Resume mode.

Resumes a partially completed installation. This is typically used to resume an installation after the system was restarted due to the installation of one or more prerequisites.

Note: This option is ignored by new installations, which always run as Installer.

Corresponds to TsuRunMode value 5.

Installation options

In addition to one of the run mode options, you can use the following options to further modify Setup's behavior:

Option Description
/a
/an

Require Administrator rights (equivalent to /a5)
Set the installation level to n.

This option modifies the Installation level attribute set on the Installer options project page. The current installation level is available through the TsuInstallLevel variable. The level n can be one of the following:

Value Description
/a0 No access checks performed
/a1 Install for Current User only
/a2 Install for All Users if possible, else Current User
/a3 Install for All Users if possible, else query Current User
/a4 Install for All Users if possible, else fail
/a5 Install as Administrator if possible, else fail
/bn

Set reboot mode n. This option determines how Setup handles system restarts at the end of the installation or removal process. The current reboot mode is available and may be set through the TsuRebootMode variable. The available levels are:

Value Description
/b0 Never reboot. This is particularly useful to prevent undesired system restarts during unattended installation or removal. Depending on the circumstances, a subsequent reboot might be required to complete the installation or removal process. This is indicated by an exit code of 12 (Reboot required; see Exit codes below).
/b1 Reboot as needed. This is the default behavior and causes Setup to reboot automatically if required. In interactive mode, the customer can still prevent the reboot at the end of the installation.
/b2 Always reboot. This causes Setup to reboot at the end of the installation or removal process without further ado. Use this option with caution.
/cn

Set integrity checking mode n. This option determines how Setup checks the integrity of the installation package at the start of the installation. The available levels are:

Value Description
/c0 Do not check. No integrity check is performed.
/c1 Check only writable packages, not read-only ones. This skips integrity checking for packages that are stored on CD-ROM and similar read-only media, or that are manually marked read-only. This is the default option.
/c2 Full integrity check. Calculates a checksum on the entire package and compares that with the checksum that was stored in the package when it was built. If the check fails, the installer will exit with error code 3 (Invalid or missing setup database; see Exit codes below).
/d:dbpath Specify the path to the installation database. This is an advanced option and should not normally be used.
/emask

Set the error mask to mask. The error mask determines which runtime errors will terminate the installation. The initial mask is set on the Installer options project page; the /e option adds another mask to this. The effective error mask is initial_mask & mask, where '&' represents the binary 'and' operation.

To enable specific error types, set mask to the combination of the error values shown below. If you leave out an error type, it is ignored by the installer. To make the installer ignore all runtime errors, specify /e0. This is not recommended, because it may leave the product partially installed or partially uninstalled. However, in emergencies it may help to install or remove the product.

Note: Even if you include an error type in the /e option, it will only terminate the installation if it's also enabled on the Installer options project page. In other words: you can only remove error types, not add them.

You may specify mask in decimal or hexadecimal; in the latter case, you must prefix it with 0x. For example, /e255 and /e0xFF are equivalent.

Decimal Hexadecimal Effect
1 0x00000001 Fail on file installation errors
2 0x00000002 Fail on file registration errors
4 0x00000004 Fail on shortcut creation errors
8 0x00000008 Fail on registry errors (also environment on NT-based systems)
16 0x00000010 Fail on INI file errors
32 0x00000020 Fail on environment errors
64 0x00000040 Fail on service install errors
128 0x00000080 Fail on service control errors
256 0x00000100 Fail on extension DLL runtime errors
512 0x00000200 Fail on extension DLL fail requests
1024 0x00000400 Fail on user cancellation
2048 0x00000800 Fail on upgrade failures
4096 0x00001000 Fail on external program exit codes
8192 0x00002000 Fail on assembly registration errors
16384 0x00004000 Fail on Windows Mobile installation errors
/l

Show all valid locale languages in a multilingual installer, even if they don't use the current ANSI code page. This might result in some text being replaced by ??? characters or mapped to the wrong glyphs.

Note: This option applies to the ANSI versions of Setup.exe only; Unicode versions always show all valid locale languages. See Setup stubs for an explanation of the various available Setup.exe variations.

/l:langid

Use langid as the user interface language, if the installer has been localized for this language on the Languages page. If not, then the language selection process as for the Languages: Multilingual, auto package option is used to select the most suitable installation language.

As a special case, if you specify /l:0 (i.e., a langid value of zero), then the installer will use the best matching available language for the user's system. This is equivalent to specifying the Languages: Multilingual, auto package option.

langid must be the decimal or hexadecimal Windows language identifier of the desired language; hexadecimal language identifiers must start with 0x ("zero ex"). Therefore, /l:1033 and /l:0x409 are equivalent and both designate US English. See the MSDN web site for a complete list of language identifiers.

Note 1: The language selection process only has effect during installation; the uninstaller always uses the same language as was used during installation.

Note 2: If this option is specified, then the installation language is always chosen without user interaction, even if there is no exact match for the requested language.

/log:logpath

Save the installer's log file to logpath after the installation or removal is complete.

The logpath must be a fully qualified file path that includes the final log file name, for example C:\Windows\MyLog.log. You may use symbolic variables in logpath, but you must then "quote" the option to prevent Windows from misinterpreting the < and > characters. For example, the following is a valid and properly quoted /log option: /log:"<WindowsFolder>\MyLog.log"

This option overrides the default log file handling.

Note: The new logpath must be on the same disk volume as the default log file location; in practice, this means that logpath must reside on the same volume as the installing user's %TEMP% folder.

/p:password Use password as the password for password-protected Setup packages. This password must match the one that was specified in the Password field of the package when the Setup package was built.
/q
/qn

Perform a silent (quiet, unattended) installation. During silent installations, the normal Setup wizard is suppressed and the entire installation, registration, or uninstallation process is performed without user intervention. This feature is intended for unattended installations and removals.

The second form allows you to specify a silence level n as follows:

Value Description
/q0 Not a silent install; the normal Setup wizard is shown after all. This option is mostly useful if you generate the Setup command line programmatically, or to override a prior /q option (for example, one that was preset in the installer).
/q1 Silent install; equivalent to /q.
/q2 Invisible install. In this mode, the entire installation, registration, or uninstallation process is performed without user intervention and with a completely hidden user interface. (The Setup process will still appear in the Windows Task Manager's list of running processes, though.)

Note - In silent installation mode you cannot specify user registration information for use on the Setup - Registration Information page. Only default user registration, if you specified any on the User interface project page, takes place in silent installation mode.

For multilingual installers running in silent mode, Setup always installs the default language version. In practice, this means that installation takes place in the locale of the installing user account, which is usually what is desired. See the Languages option in the package documentation for the details of this selection process.

The current silence level is available and may be set through the TsuQuiet variable.

/s:sourcedir

Specify the path to the folder that contains the uncompressed installation source files, i.e., the files that are distributed as plain files instead of as part of the compressed installation archive. The actual files may be stored in the sourcedir folder itself or in one of its subfolders.

This option assigns a new value to the <SourceDir> variable. For new installations, this variable is set automatically to the folder that contains the original distribution package; existing installations reuse the most recently used path, unless you override it with this command line option.

/u
/un

Uninstall/upgrade mode. Indicates that the uninstaller is running as part of an upgrade. In other run modes, this option sets the TsuUpgrade variable, but is otherwise ignored. /u is equivalent to /u1 and sets TsuUpgrade to 1; /un sets TsuUpgrade to n.

In Uninstaller mode, it tells Setup to uninstall as part of an upgrade. In that case, Setup performs the uninstallation as per normal, except that in-use files are not queued for delayed removal on the next Windows restart. This prevents problems during upgrades, when delayed file removal by Windows could accidentally remove the new version of a file.

The current upgrade level is available through the the TsuUpgrade variable.

/z:tizpath Specify the path to the TIZ archive, i.e., the file that contains the compressed distribution files. This is an advanced option and should not normally be used.

Exit codes

InstallMate's Setup program returns an exit code that indicates the result of its actions. This result code is mainly useful if you use Setup in silent installation mode in a batch file, where it can be tested through the %ERRORLEVEL% variable (Windows NT4 and later only) or by using an IF ERRORLEVEL statement. The following exit codes are currently defined.

Exit code Description
-1 Internal error (anything < 0)
0 Success
1 Invalid license code or evaluation period expired
2 Initialization error
3 Invalid or missing setup database
4 Error while saving the setup database
5 Installation cancelled
6 Other installation failure
7 Invalid run mode
8 Error while creating the user interface
9 Invalid command line option
10 Administrator rights required
11 Target system requirements not met
12 Reboot required
13 Application is currently running
14 Previous version detected
15 Incorrect or missing password
16 Insufficient disk space
17 Insufficient access rights
18 Extension DLL returned error
19 Error while running installer actions
20 Another instance of the same product installer is already running
The following exit codes are generated by the pre-Setup loader stub:
249 Missing or invalid TSU.DLL installer library
250 Account name not available
251 WaitForProcess() failed while waiting for Setup.exe to terminate
252 CreateProcess() failed: could not start Setup.exe
253 ANSI installer required, but not included in the package
254 Invalid loader stub
255 General function failure

Using the start /wait option when running Setup from the command line

If you run Setup from a batch file or command line prompt, the default Windows behavior is to continue with the next command as soon as Setup is started; it does not wait until Setup has finished. As a result, the value of %ERRORLEVEL% does not necessarily reflect Setup's exit code.

To remedy this, run Setup as follows:

start /wait Setup.exe other_options...

This ensures that the command does not return until Setup has exited.

Providing a dummy "title" field for the CMD.EXE start command

[Windows NT/2000/XP/Vista and later] If the Setup.exe program path in the start command contains spaces, you must quote it. However, the start command on Windows NT/2000/XP/Vista and later interprets the first quoted string as the program title and not as a program path. Therefore, you should include a dummy, quoted program title prior to the actual program path, thus:

start /wait "title" "setup_path" other_options...

This is only necessary if you quote setup_path for some reason.

Note that this tip only applies to the Cmd.exe command interpreter used on Windows NT/2000/XP/Vista and later systems; the Command.com command interpreter on Windows 9x systems does not support a title option and therefore requires no workaround.

Setup log file

Detailed information about the Setup process is written to the diagnostic log file. Please consult this log file to find out what actions the installer took. You can decode the information in the log file by expanding the log file.

The installer's log file is written to the %TEMP% folder of the installing user (which could be Administrator if the installer is running elevated). The %TEMP% folder usually resolves to one of the following:

Windows Vista, 2008, 7, 8, 2012, 10
C:\Users\<user name>\AppData\Local\Temp
Windows 2000, XP, 2003
C:\Documents and Settings\<user name>\Local Settings\Temp
Windows NT4
C:\WinNT\Temp
Windows 95, 98, Me
C:\Windows\Temp

The initial name of the installation log file is is PackageName.log during a new installation or Setup.log for all other sessions; it will be renamed to PackageName-yyyymmddThhmmss-type.log at the end of the session, where type indicates the type of session: Install, Remove, Register, or a few others.

Notes

Expanding a log file

The Setup log files are written as Unicode UTF-8 encoded text files with only log message codes and their runtime parameters. You can expand these message codes to complete message lines (and thus make the log file easier to read) by using the LogX.exe program that comes with InstallMate 9. You can find this program in the C:\Program Files\InstallMate 9\Bin folder on your system, or wherever you installed InstallMate 9.

The LogX.exe program is a console application, so you must open a command prompt window to use it. Its syntax is very simple:

LogX.exe [path\]logfile.log

The logfile.log argument must be the name of the log file, optionally prefixed with the path to the log file's parent folder if the log file is not located in the current folder. The LogX.exe program will replace the original log file by its expanded version, which you can then open in any plain text editor that understands Unicode UTF-8 encoded text files. This includes Windows Notepad.

Setup installation location: <TinProductFolder>

After installation, the InstallMate installation program and its auxiliary files are installed on the target system in <TinProductFolder>. This translates to one of the following locations, depending on the target system version. For non-English versions of Windows, some of the folder names may be localized.

Windows Vista, 2008, 7, 8, 2012
C:\ProgramData\InstallMate\{...product GUID...}
Windows 2000, XP, 2003
C:\Documents and Settings\All Users\Application Data\InstallMate\{...product GUID...}
Windows NT4
C:\WinNT\Profiles\All Users\Application Data\InstallMate\{...product GUID...}
Windows 95, 98, Me
C:\Windows\All Users\Application Data\InstallMate\{...product GUID...}

The above locations are used for All Users or Administrator level installations. If the installation was performed as a Current User installation, then the locations become:

Windows Vista, 2008, 7, 8, 2012
C:\Users\<user name>\AppData\Local\InstallMate\{...product GUID...}
Windows 2000, XP, 2003
C:\Documents and Settings\<user name>\Application Data\InstallMate\{...product GUID...}
Windows NT4
C:\WinNT\Profiles\<user name>\Application Data\InstallMate\{...product GUID...}
Windows 95, 98, Me
C:\Windows\All Users\Application Data\InstallMate\{...product GUID...}

Note that the Windows 9x location is unchanged, because those systems lack any effective security options and all installations are performed at the Administrator level.