Skip to content

Command Line Reference

Jump to bottom
Rod Christiansen edited this page Sep 5, 2026 · 2 revisions

Command Line Reference

The command-line tool is managedbootstrapinstall.exe, installed to C:\Program Files\BootstrapMate and added to the system PATH. This page lists every switch it implements, what the process returns, and the invocations you are likely to need.

The executable's manifest requests requireAdministrator, and it re-checks its token at startup. If it is not elevated it prints an error and offers to relaunch itself under UAC; with --silent it refuses to raise a UAC prompt and returns 1. Every run also takes a Global\BootstrapMate.SingleInstance mutex and waits up to 30 minutes for a concurrent run to finish.

Argument parsing happens in two passes. --silent, --verbose and -v are scanned across the whole argument list before anything else; --version and -V are handled only in position 0; everything else is matched in a lowercased switch over the remaining arguments. There is no default: arm, so an argument the tool does not recognise is silently discarded.

Summary

Switch Argument Required Default Summary
--url URL No configured manifest URL Manifest to download and execute
--help, -h — No — Print help and exit
--version, -V — No — Print version and exit; first argument only
--status — No — Print installation status and exit
--clear-status — No — Clear status data and exit
--clear-cache — No — Clear all caches and exit
--reset-chocolatey — No — Full Chocolatey reset; prompts on stdin
--force — No off Deprecated; clears all caches aggressively
--verbose, -v — No off Debug lines on the console
--silent — No off No console output at all
--no-dialog — No off Disable the progress dialog
--blur-screen — No off Run the progress dialog fullscreen
--dialog-title text No Setting Up Your Device Progress dialog title
--dialog-message text No Please wait while we install required software... Progress dialog message
--pipe name No none Mirror log lines to a named pipe
--save-settings — No — Persist the remaining switches to HKCU
--save-settings-file path No — Persist a JSON config file to HKCU

Switches

--url <url>

  • Type: String (URL)
  • Default: the configured manifest URL, or the built-in default
  • Required: No

The manifest to download and execute. It bypasses ConfigManager entirely and is assigned directly, so it overrides every registry and policy source. Given without a following value, the tool prints ERROR: --url requires a URL parameter and returns 1.

Omit it and the effective URL comes from the precedence chain in Preferences.

--help, -h

  • Required: No

Prints the help block and returns 0 immediately, without processing any manifest. -h is matched after lowercasing, so -H also works.

--version, -V

  • Required: No

Prints the build version and returns 0.

This is handled before elevation, logging and the single-instance mutex, and only when it is the first argument. --version is matched case-insensitively; -V is matched with an ordinal comparison, so case matters. Anywhere other than position 0, -V is lowercased by the main parsing loop, falls into the -v case, and is treated as the verbose switch instead — it prints nothing and the run proceeds. Put it first:

managedbootstrapinstall.exe --version

--status

  • Required: No

Prints the recorded stage, architecture, start and completion times, exit code, last error, run id and manifest URL for each phase, then a completion block, then a set of path hints.

The completion block and the path hints read HKLM\SOFTWARE\BootstrapMate, which is not where status is written — StatusManager writes to HKLM\SOFTWARE\Cimian\BootstrapMate. The LastRunVersion this switch reports is the one the MSI writes at install time, not evidence of a completed run. Query the real keys directly instead; see Troubleshooting and Gotchas.

--clear-status

  • Required: No

Deletes HKLM\SOFTWARE\BootstrapMate\Status\{phase} and C:\ProgramData\BootstrapMate\status.json. Neither is what the tool writes, so this switch clears nothing real. The live status lives under HKLM\SOFTWARE\Cimian\BootstrapMate\Status and in C:\ProgramData\ManagedBootstrap\status.json.

--clear-cache

  • Required: No

Clears the BootstrapMate package cache and the Chocolatey caches, then exits. Note that a normal run already empties the package cache at startup, and a cached file only survives a run when the install that used it failed.

--reset-chocolatey

  • Required: No

Performs a full Chocolatey reset. It asks for y/N confirmation on stdin, so it blocks indefinitely under a scheduled task or any other non-interactive host. Cancelling returns 0.

--force

  • Default: off
  • Required: No

The help text describes it as deprecated, because downloads are always fresh and the cache exists only for inspection. It still has an effect: it triggers the aggressive cache clear, which deletes the BootstrapMate cache directory and the Chocolatey temp, lib-bad, .chocolatey and logs directories and runs choco cache clear. The self-heal scheduled task the MSI registers passes --force on every daily run.

--save-settings explicitly does not persist this switch.

--verbose, -v

  • Default: off
  • Required: No

Sends Debug lines to the console. --verbose is matched case-insensitively; -v is matched with an ordinal comparison in the pre-scan, so lowercase is required there. The log file receives Debug lines regardless. Some output is only visible with this switch — notably sbin-installer's stdout and stderr, and the "dialog binary not found" message.

--silent

  • Default: off
  • Required: No

Suppresses all console output. It does not suppress the log file. An unelevated run with --silent returns 1 without doing anything, because the elevation helper refuses to raise a UAC prompt in silent mode.

--no-dialog

  • Default: off
  • Required: No

Disables the progress dialog. This is the only switch routed into ConfigManager.

--blur-screen

  • Default: off
  • Required: No

Passes --fullscreen to the dialog binary so it covers the screen behind it. This switch is implemented but is not listed in the tool's own help or usage output.

--dialog-title <text>

  • Type: String
  • Default: Setting Up Your Device
  • Required: No

Sets the dialog window title for this run. Given without a following value it is ignored and the default stands.

--dialog-message <text>

  • Type: String
  • Default: Please wait while we install required software...
  • Required: No

Sets the dialog message for this run. Given without a following value it is ignored.

--pipe <name>

  • Type: String
  • Default: none
  • Required: No

Connects to an existing named pipe on the local machine, with a five-second connect timeout, and mirrors every log line to it. A failed connect logs a warning and the run continues; a broken pipe silently stops further pipe writes. The GUI does not use this path — it tails the log file instead.

--save-settings

  • Required: No

Parses the remaining arguments into a configuration object and writes it to HKCU\SOFTWARE\BootstrapMate\Settings, then returns 0 or 1. No manifest is processed. It accepts --url, --no-dialog, --dialog-title, --dialog-message, --dialog-icon, --silent, and --verbose/-v. Any value already set under the policy key is skipped.

--dialog-icon is accepted here and nowhere else: there is no --dialog-icon switch on a normal run, and the saved DialogIcon value is never used. See Preferences.

--save-settings-file <path>

  • Type: String (file path)
  • Required: No

Reads a JSON BootstrapMateConfig from the given path, writes it to HKCU\SOFTWARE\BootstrapMate\Settings, and deletes the file, then returns 0 or 1. Given without a path it prints ERROR: --save-settings-file requires a file path and returns 1.

Switches the GUI sends that the CLI ignores

The GUI builds its run arguments from the same configuration object as everything else and emits four switches the CLI has no case for. Because the parsing loop has no default: arm, they are discarded without a message:

  • --headers <value> — the AuthorizationHeader value. Configure it in the registry instead.
  • --follow-redirects
  • --dry-run
  • --reboot

The last three correspond to settings that are inert anyway. A GUI run with Dry run ticked installs packages for real.

Exit codes

Code Meaning
0 The manifest was processed without an unhandled exception
0 --version, --help, or the usage block was printed
0 Elevation relaunch succeeded, or --reset-chocolatey was cancelled
1 Not elevated and the user declined, or elevation failed
1 Timed out after 30 minutes waiting for another instance
1 --url or --save-settings-file given without its value
1 No manifest URL could be resolved
1 An unhandled exception while processing the manifest — a download or parse failure
1 A --save-settings, --status, --clear-status, --clear-cache or --reset-chocolatey failure

A zero exit does not mean every item installed. Each item is installed inside a try/catch and a failure is logged, the cached file kept for inspection, and the loop continues to the next item. A run in which every single package failed still returns 0 and still writes LastRunVersion. Do not build a detection rule or a monitoring check on the exit code alone.

To judge a run, count Failed to install package lines in the log, check that C:\ProgramData\ManagedBootstrap\cache is empty, and read Stage under HKLM\SOFTWARE\Cimian\BootstrapMate\Status\SetupAssistant and ...\Userland. See Logging and Reporting.

Examples

Run a manifest once, interactively, with full console detail:

managedbootstrapinstall.exe --url https://example.com/bootstrap/bootstrapmate.json --verbose

Run unattended from a scheduled task or a deployment tool, with no console output and no dialog:

managedbootstrapinstall.exe --url https://example.com/bootstrap/bootstrapmate.json --silent --no-dialog

Run against the manifest URL already set by policy or by the MSI, taking no arguments at all:

managedbootstrapinstall.exe

Show the version. It must be the first argument:

managedbootstrapinstall.exe --version

Show what the last run recorded, remembering the caveat above about which registry root this reads:

managedbootstrapinstall.exe --status

Persist a manifest URL and a custom dialog title to the current user's settings without running anything:

managedbootstrapinstall.exe --save-settings --url https://example.com/bootstrap/bootstrapmate.json --dialog-title "Preparing your device"

See also

Introduction

The Manifest

Configuration

Operations

More

Clone this wiki locally