Skip to content

Item Types

Rod Christiansen edited this page Oct 8, 2026 · 2 revisions

Item Types

An item's type decides how the downloaded file is run, which optional keys apply, and what counts as success. Five values are handled: msi, exe, ps1 (with powershell as a synonym), nupkg and pkg. Anything else fails the item with Unsupported package type: {type}. Supported types are: msi, exe, ps1, nupkg, pkg.

type is matched case-insensitively. It is also the main ordering key inside a stage; see Stages. Whatever the type, a download with a hash must match it before anything runs; see Manifest Reference.

At a glance

type Run by Signature gate arguments target Success is
msi msiexec.exe, or sbin-installer for a Cimian-built MSI Yes Appended to msiexec; forces msiexec On the sbin-installer path Exit code 0, with retries
exe The file itself Yes The whole command line No Exit code 0
ps1, powershell powershell.exe No Appended after -File No Exit code 0
nupkg sbin-installer, else Chocolatey No Appended to either command On the sbin-installer path Exit code 0
pkg sbin-installer only No Appended to the command Yes Exit code 0

The Authenticode gate applies only to msi and exe, the formats WinVerifyTrust can validate, so expectedPublisher and allowUnsigned do nothing on other types. See Security and Package Verification.

msi

The default path is:

msiexec.exe /i "<cached file>" /qn /norestart <arguments>

/qn /norestart are always present, so an MSI never shows UI and never restarts the machine. BootstrapMate has no reboot handling; a package that needs one gets it when something else restarts the device.

Before each launch BootstrapMate waits for the Windows Installer mutex to go idle, and it retries a defined set of exit codes. That has its own page: Retries and Timeouts.

Which installer runs an MSI

A Cimian-built MSI, one that contains the marker CIMIAN_PKG_BUILD_INFO, goes to sbin-installer, which runs the package's embedded scripts, logging Using sbin-installer for Cimian MSI: {file}. Three cases go to msiexec instead:

  • sbin-installer is not present on the machine.
  • The item has arguments. Those are msiexec arguments, and sbin-installer's command line takes none.
  • The item is the sbin-installer package itself, recognised by a file or item name starting sbin-installer or SbinInstaller (ignoring punctuation and case), or a name containing System Binary Installer.

The Debug log names the reason. Third-party MSIs always use msiexec. The marker test reads the whole MSI into memory, which is worth knowing for very large MSIs. On the sbin-installer path the MSI retry policy does not apply and target does.

MSI exit codes

Exit code Treated as Effect
0 Success Item complete
1618 ERROR_INSTALL_ALREADY_RUNNING Scheduling collision Waits for the other transaction and retries without using an attempt
1603 ERROR_INSTALL_FAILURE Retryable Retried up to the attempt limit
1619 ERROR_INSTALL_PACKAGE_OPEN_FAILED Retryable Retried up to the attempt limit
1620 ERROR_INSTALL_PACKAGE_INVALID Retryable Retried up to the attempt limit
1612 ERROR_INSTALL_SOURCE_ABSENT Retryable Retried up to the attempt limit
Anything else non-zero Failure MSI installer failed with exit code: {n}

An item recognised as the installer helper (its name contains System Binary Installer or sbin-installer, or its file name contains sbin-installer) retries on any non-zero code.

3010 (reboot required) is neither retryable nor success, so an MSI that returns it fails the item even though it installed.

exe

The file is started directly, with arguments joined by spaces as its whole command line. Nothing is added, so supply the vendor's silent switches yourself. Standard output is logged at INFO and standard error at WARN, both prefixed [OUTPUT] {name}: .

A non-zero exit fails the item with Executable failed with exit code: {n}. There are no retries. An installer that reports success with a non-zero code, or returns before its work is done, is misreported; wrap it in a ps1 item instead.

ps1 and powershell

Both spellings run:

powershell.exe -ExecutionPolicy Bypass -NoProfile -File "<cached file>" <arguments>

That is Windows PowerShell, not PowerShell 7, with the run's own elevated token. Output is captured as for exe. A non-zero exit fails the item with PowerShell script failed with exit code: {n}, so the script's own exit code is the only success signal; a script that swallows its errors reports success.

Scripts are not signature-checked; pin them with hash. A script whose name contains cleanup, clean, wipe, remove, delete, purge, nuclear or maintenance runs at the end of its stage. The same command runs preflight scripts, where the exit code picks the mode instead.

nupkg

If sbin-installer is present it handles the package. If not, the log records sbin-installer not found / Using Chocolatey fallback and the item goes to Chocolatey.

On the Chocolatey path BootstrapMate reads the package id and version from the .nuspec inside the .nupkg (falling back to the file name), checks whether the package is already present to choose install or upgrade, and runs Chocolatey through powershell.exe with the cache directory as a local source:

choco {install|upgrade} "<id>" --source="<cache dir>" --version="<version>" -y --acceptlicense --confirm --force --no-progress --quiet --limit-output <arguments>

Chocolatey verifies the checksums of what a package downloads. An item that genuinely needs that off sets "ignoreChecksums": true, which adds --ignore-checksums and logs a warning.

If Chocolatey is not installed, BootstrapMate installs it from https://community.chocolatey.org/install.ps1 first, so the fallback needs internet access to that host. If it finds a Chocolatey directory whose choco.exe does not work, it logs Broken Chocolatey detected, deletes C:\ProgramData\chocolatey, clears ChocolateyInstall and removes Chocolatey's directory from the machine PATH before reinstalling.

Failure message: Chocolatey {install|upgrade} failed with exit code {n}, with the captured output appended.

pkg

sbin-installer only. Without it the item fails with sbin-installer is required for .pkg packages but was not found. Please install sbin-installer first. The source marks this type for removal, so prefer msi or nupkg for new work.

The sbin-installer path

Three types can end up here: pkg always, nupkg when sbin-installer is present, and a Cimian-built msi under the conditions above. The command is:

installer --pkg "<cached file>" --target <target> <arguments>

target defaults to /. The helper is found at C:\Program Files\sbin\installer.exe, then C:\Program Files (x86)\sbin\installer.exe, C:\sbin\installer.exe, C:\Tools\sbin\installer.exe, and finally where.exe installer.exe, accepting a where hit only if its path contains sbin or System Binary so a Chocolatey shim of the same name is not mistaken for it.

A non-zero exit fails the item with sbin-installer install failed with exit code: {n} plus the captured output. sbin-installer's own output is logged at Debug.

Divergence from macOS

The macOS build has its own type vocabulary and verification model; nothing in the type values transfers between the two. See https://github.com/bootstrapmate/bootstrapmate-macintosh/wiki/Item-Types.

See also

Clone this wiki locally