Skip to content

Command Line Reference

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

Command Line Reference

Every flag the BootstrapMate CLI accepts, its type, default and effect. You need this page when you are testing a manifest by hand, or reading the command line the helper used out of a log. In a normal enrollment the LaunchDaemon starts the binary with no arguments at all, so everything comes from the profile instead — see Preferences.

The command is a single flat command. There are no subcommands.

On an installed Mac the binary is at:

/usr/local/bootstrapmate/managedbootstrapinstall

That is a symlink to the copy inside the app bundle, at /Applications/Utilities/BootstrapMate.app/Contents/MacOS/managedbootstrapinstall. It installs packages and runs scripts as root, so it must be run as root.

Flag summary

Flag Type Default Summary
--jsonurl <string> Option none Manifest URL to load
--headers <string> Option none Authorization header value for downloads
--dry-run Flag false Suppresses downloads only; installs and scripts still run
--follow-redirects Flag false Has no effect
--userscript Flag false Run only userland scripts, then exit
--reboot Flag false Reboot after a successful run
--silent Flag false No console output
--verbose Flag false Verbose logging
--no-dialog Flag false Disable the SwiftDialog window
--dialog-title <string> Option none Dialog title
--dialog-message <string> Option none Dialog message
--network-timeout <int> Option 120 Seconds to wait for network
--reporting-url <string> Option none Endpoint to POST the run summary to
--no-verify-signature Flag false Skip package signature verification
--expected-team-id <string> Option none Require this Apple Team ID
--allow-unsigned Flag false Allow untrusted or unsigned packages
--version Flag — Print the version string and exit
--help, -h Flag — Print usage and exit

--jsonurl <string>

  • Type: String
  • Default: none

The URL of the manifest to download and execute. Overrides the url preference. If neither is set, BootstrapMate waits up to 300 seconds for a management profile, then exits 1.

--headers <string>

  • Type: String
  • Default: none

The complete value of an Authorization header, for example Basic … or Bearer …. It is sent on the manifest request and on every payload download, whatever host the payload URL points at. Overrides the headers preference.

--dry-run

  • Type: Flag
  • Default: false

Downloads nothing and installs nothing. Each item is logged as [Dry Run] Would download <name>. Useful for confirming a manifest parses and its stage layout is what you expect.

--follow-redirects

  • Type: Flag
  • Default: false

This flag has no effect. The value is threaded through the download API, but no redirect-controlling delegate is installed, so redirects are followed either way. See Troubleshooting and Gotchas.

--userscript

  • Type: Flag
  • Default: false

Runs only the items of type userscript in the userland stage, then exits. Per-script failures are ignored, and this mode always exits 0.

--reboot

  • Type: Flag
  • Default: false

Reboots the Mac five seconds after the run finishes, and only when the run succeeded. A failed run never reboots.

--silent

  • Type: Flag
  • Default: false

Suppresses all console output. It also disables the SwiftDialog window. File logging is unaffected.

--verbose

  • Type: Flag
  • Default: false

Writes debug-level lines to the console, and makes BootstrapMate log the effective configuration under Current Configuration: near the start of the run. This is the fastest way to see which manifest URL and which security settings a Mac actually resolved.

--no-dialog

  • Type: Flag
  • Default: false

Runs headless, with no SwiftDialog progress window. The dialog is also skipped automatically when SwiftDialog is not installed at /usr/local/bin/dialog.

--dialog-title <string>

  • Type: String
  • Default: none, so the built-in Setting up your Mac is used

Sets the title of the progress window. This is the only way to change the title; the dialogTitle preference is not consulted.

--dialog-message <string>

  • Type: String
  • Default: none, so the built-in Please wait while we configure your device... is used

Sets the message shown under the title. As with the title, the matching preference is not consulted.

--network-timeout <int>

  • Type: Int
  • Default: 120

How many seconds to wait for a satisfied network path before continuing. On timeout BootstrapMate performs one DNS resolution as a last check, logs Network check timed out - proceeding anyway, and carries on regardless. The wait is never fatal. This option is also the only source of the timeout; the networkTimeout preference is not consulted.

--reporting-url <string>

  • Type: String
  • Default: none

Where to POST the JSON run summary when the run ends. Overrides the reportingUrl preference. There is no matching flag for the reporting Authorization header, which can only come from the reportingHeader preference.

--no-verify-signature

  • Type: Flag
  • Default: false

Turns off package signature verification entirely. When absent, the flag does not force verification on — the preference value, which defaults to enabled, decides. See Security and Package Verification.

--expected-team-id <string>

  • Type: String
  • Default: none, meaning any signature macOS trusts is accepted

Requires installer packages to be signed by this ten-character Apple Team ID. A mismatch is always refused, including when unsigned packages are allowed.

--allow-unsigned

  • Type: Flag
  • Default: false

Allows a package with no signature, or one macOS does not trust, to install. When absent, the flag does not force the opposite — the preference decides. It never overrides a Team ID mismatch.

--version

  • Type: Flag

Prints a version string and exits. Note that this string is generated at the moment it is read, not at build time, so it reflects the current date and time rather than the build you installed. To find the real installed version, read the app bundle instead:

defaults read /Applications/Utilities/BootstrapMate.app/Contents/Info CFBundleShortVersionString

--help, -h

  • Type: Flag

Prints usage and exits.

Exit codes

Code Meaning
0 All stages completed, or the preflight script exited 0 and the run was deliberately skipped, or --userscript mode finished
1 The manifest could not be downloaded or decoded; or no manifest URL was configured; or a stage failed; or the process received SIGTERM

There are no other exit codes. A failed item inside the setup assistant stage is recorded but does not by itself abort the run, though it does make the run report as failed.

Examples

Check which build is installed. Use the bundle version, not --version, for the reason given above.

defaults read /Applications/Utilities/BootstrapMate.app/Contents/Info CFBundleShortVersionString

Run a manifest by hand.

sudo /usr/local/bootstrapmate/managedbootstrapinstall --jsonurl https://example.com/bootstrap/manifest.json

Validate a manifest without touching the Mac: verbose, headless, and installing nothing.

sudo /usr/local/bootstrapmate/managedbootstrapinstall --jsonurl https://example.com/bootstrap/manifest.json --verbose --dry-run --no-dialog

Run a manifest served from an origin that requires an Authorization header.

sudo /usr/local/bootstrapmate/managedbootstrapinstall --jsonurl https://example.com/bootstrap/manifest.json --headers "Bearer YOUR_AUTH_TOKEN_HERE"

Enforce a signer for every package in the run, and report the result to a collector.

sudo /usr/local/bootstrapmate/managedbootstrapinstall --jsonurl https://example.com/bootstrap/manifest.json --expected-team-id AB12CD34EF --reporting-url https://example.com/bootstrap/report

Re-run only the userland scripts on a Mac that is already provisioned.

sudo /usr/local/bootstrapmate/managedbootstrapinstall --jsonurl https://example.com/bootstrap/manifest.json --userscript --verbose

See also

Introduction

The Manifest

Configuration

Operations

More

Clone this wiki locally