CLI Reference

CLI Reference

Every executable Cimian ships, every flag it accepts, and every exit code it returns. All binaries install to C:\Program Files\Cimian\, which the installer adds to the machine PATH.

Tools split into two families:

Family	Tools	Runs on
Client	managedsoftwareupdate, cimitrigger, cimiwatcher, cimistatus, Managed Software Center	Managed endpoints
Repository	cimiimport, cimipkg, makepkginfo, makecatalogs, manifestutil, repoclean	An admin workstation or CI runner with access to the repo

Conventions and inconsistencies

The suite grew over time and the flag style is not uniform. Rather than pretend otherwise, here is the map:

Quirk	Detail
Two parser libraries	managedsoftwareupdate uses CommandLineParser ([Option] attributes); every other tool uses System.CommandLine. --help output therefore looks different between them.
Version flag	makecatalogs, manifestutil and repoclean accept only -V (no --version). managedsoftwareupdate accepts -V and --version, but the fast path only fires when it is the sole argument. cimiimport, makepkginfo, cimitrigger and cimiwatcher have no version flag at all.
Underscore vs hyphen	Mixed within single tools. cimiimport has both --repo_path and --preinstall-script; makepkginfo has both --preinstall_script and --pkg-version.
cimitrigger --force	Declared as a subcommand whose name happens to start with dashes, not as an option. It takes a positional mode argument and does not compose with other flags.
--OnDemand	The only mixed-case flag in the suite (makepkginfo). It is case-sensitive.

There is no shared exit-code enum. Each tool hard-codes its own values; the only codes above 1 anywhere in the suite come from managedsoftwareupdate --self-check.

---

managedsoftwareupdate

The agent. Reads the client's manifest, resolves catalogs, decides what needs installing or removing, downloads, installs, and writes the session report. The direct counterpart of Munki's managedsoftwareupdate.

Requires administrator for any real run: UpdateEngine checks for elevation and returns 1 with "Administrative access required." if it is missing. Informational flags (--show-config, --cache-status, --self-check, --loop-status) work unelevated. Only one run at a time — a global mutex (Global\CimianManagedSoftwareUpdate_v2) makes a second instance exit 1.

No subcommands, no positional arguments.

Run modes

Flag	Short	Type	Default	Effect
--auto	-a	bool	false	Perform automatic updates. The mode the hourly scheduled task uses.
--checkonly	-c	bool	false	Check for updates but do not install them.
--installonly	-i	bool	false	Install pending updates without checking for new ones.
--bootstrap	-b	bool	false	Run in bootstrap mode (used at service startup).
--item		string list	none	Process only the named item(s). Repeatable, or comma-separated.
--manifest	-m	string	none	Process only the named server manifest.
--local-only-manifest		string	none	Use a local manifest file instead of the server manifest.
--quiet	-q	bool	false	Suppress output.
--config		string	none	Path to an alternate configuration file.

Bootstrap

Flag	Type	Default	Effect
--set-bootstrap-mode	bool	false	Create the bootstrap flag file so the next watcher poll runs a full cycle.
--clear-bootstrap-mode	bool	false	Remove the bootstrap flag file.

See Bootstrap Mode for what the flag file does.

Self-update

Flag	Type	Default	Effect
--check-selfupdate	bool	false	Report whether a self-update is pending.
--selfupdate-status	bool	false	Show detailed self-update status and exit.
--clear-selfupdate	bool	false	Clear the pending self-update flag.
--perform-selfupdate	bool	false	Perform the pending self-update in this process. Internal use.
--restart-service	bool	false	Restart the CimianWatcher service and exit, which is what applies a queued self-update.

See Self-Update.

Health and cache

Flag	Type	Default	Effect
--self-check	bool	false	Verify the Cimian installation is intact and exit. Used by the Watchdog scheduled task.
--validate-cache	bool	false	Validate cache integrity and remove corrupt files.
--cache-status	bool	false	Show cache status and statistics.
--clean-cache	bool	false	Perform a full cache cleanup and exit.

Loop suppression

Flag	Type	Default	Effect
--loop-status	bool	false	Show install-loop suppression status and exit.
--clear-loop	string	none	Clear loop suppression for a package. Pass all to clear every suppression.

See Install Loop Prevention.

Preflight and postflight

Flag	Type	Default	Effect
--no-preflight	bool	false	Skip the preflight script.
--no-postflight	bool	false	Skip the postflight script.
--preflight-only	bool	false	Run only the preflight script and exit.
--postflight-only	bool	false	Run only the postflight script and exit.

Status window and output

Flag	Short	Type	Default	Effect
--show-status		bool	false	Show the status window during operations.
--status-port		int	19847	TCP port of the GUI status listener. Managed Software Center passes its own port so the two listeners never collide.
--show-config		bool	false	Print the resolved configuration and exit.
--version	-V	bool	false	Print the version and exit.
--verbose	-v	count	0	Increase verbosity. Repeatable.

Verbosity is stripped from argv and counted before parsing, so -v, -vv, -vvv and repeated -v -v all work. One or more sets the log level to INFO; three or more sets it to DEBUG and enables stack traces.

Exit codes

Code	Meaning
0	Success, or an informational flag completed.
1	Argument parse failure; another instance already running; not administrator; partial install failure; preflight or postflight script failure; a self-update or cache operation failed; unhandled exception.
2	--self-check only: drift detected — one or more of managedsoftwareupdate.exe, cimitrigger.exe, cimiwatcher.exe is missing from the install directory. A marker is written to C:\ProgramData\ManagedInstalls\cimian_selfcheck.json.
3	--self-check only: the marker file could not be written, or an unexpected exception occurred.

Examples

Run a full automatic cycle with verbose logging:

managedsoftwareupdate --auto -vv

Dry-run the whole manifest without installing anything:

managedsoftwareupdate --checkonly -vv

Reinstall one item and nothing else:

managedsoftwareupdate --item Firefox -vv

Test a single server manifest without touching the assigned one:

managedsoftwareupdate --manifest "Shared/Labs/Rendering" -vv

---

cimitrigger

Kicks off a managedsoftwareupdate run from an unelevated context, obtaining elevation itself. Its manifest requests asInvoker deliberately — the whole point is that it escalates on demand, first by asking the CimianWatcher service, and falling back to a Start-Process -Verb RunAs elevation prompt.

The root command has no options and no positional arguments.

Subcommand	Arguments	Description
gui	none	Update with the GUI. Always shows the CimianStatus window when a user is logged in.
headless	none	Smart headless update. Tries the service first, falls back to direct elevation.
debug	none	Run diagnostics to troubleshoot trigger problems.
--force	mode (required: gui or headless)	Force direct elevation, skipping the service attempt.

Exit codes

Code	Meaning
0	Success. debug always returns this.
1	gui, headless or --force reported failure; parse error.

An unrecognised mode value under --force surfaces as an unhandled ArgumentException.

cimitrigger gui

cimitrigger --force headless

See CimiTrigger Troubleshooting and Privilege Elevation.

---

cimiwatcher

The CimianWatcher Windows service host, and its own service-control CLI. It polls for bootstrap flag files and launches managedsoftwareupdate when one appears.

Requires administrator. The application manifest requests requireAdministrator, so the process will not start unelevated.

When the process is started by the Service Control Manager it detects that and runs as a service host; argv is then only used for generic .NET host configuration. Otherwise it parses subcommands. Unmatched tokens are an error.

Subcommand	Description
install	Install the CimianWatcher Windows service.
remove	Remove the CimianWatcher Windows service.
start	Start the service.
stop	Stop the service.
pause	Pause the service.
continue	Resume the service after a pause.
status	Show service status.
debug	Run the file watcher in console debug mode rather than as a service.
service	Run as a Windows service. Internal use; hidden from help.

No subcommand takes a flag or an argument.

Exit codes

Code	Meaning
0	The management verb succeeded; status found the service installed; debug exited cleanly; the service host shut down cleanly.
1	The management verb failed; status found the service not installed; debug threw; the service host hit a fatal exception; parse error.

cimiwatcher install

cimiwatcher debug

See CimianWatcher Service.

---

cimistatus

The WPF status window that shows update progress. It is also the background status server when running under SYSTEM.

It parses no command-line arguments of its own. Only the generic .NET Generic Host conventions apply. Mode selection is environmental, not a flag: the process runs in background/service mode when the user name is SYSTEM or USERPROFILE is empty, and in UI mode otherwise, behind a single-instance mutex (CimianStatusSingleInstance). A second launch brings the existing window to the foreground and returns.

Exit code is always the implicit 0 unless the runtime faults.

See CimianStatus UI.

---

Managed Software Center

The end-user self-service catalogue. A WinUI 3 application; the equivalent of Munki's Managed Software Center.

The executable name contains spaces: Managed Software Center.exe.

It parses no command-line arguments. It runs asInvoker — an ordinary user launches it without a UAC prompt, and it reaches the elevated agent indirectly through cimitrigger and the CimianWatcher service. That indirection is why managedsoftwareupdate --status-port exists: the app runs its own status listener on its own port.

Startup and crash lines go to C:\ProgramData\ManagedInstalls\msc_crash.log.

Code	Meaning
0	Normal exit.
1	COM wrapper initialisation or application start threw.

---

cimiimport

Imports an installer into the repository: extracts metadata, writes a pkgsinfo file, copies the payload into pkgs/, and then shells out to makecatalogs (--repo_path <path> --silent). If the repo is a git working tree it runs git pull first. The counterpart of Munki's munkiimport.

Positional argument: installerPath — the installer to import. If omitted, the tool prompts on stdin.

Flag	Short	Type	Default	Description
--installs-array	-i	string list	empty	Add a path to the generated installs array. Repeatable.
--repo_path		string	none	Override the repository path.
--arch		string	none	Override architecture, e.g. x64,arm64.
--uninstaller		string	none	Path to an optional uninstaller.
--minimum_os_version		string	none	Minimum Windows version required, e.g. 10.0.19041.
--maximum_os_version		string	none	Maximum Windows version supported.
--minimum_cimian_version		string	none	Minimum Cimian agent version required.
--preinstall-script		string	none	Path to a preinstall script.
--postinstall-script		string	none	Path to a postinstall script.
--preuninstall-script		string	none	Path to a preuninstall script.
--postuninstall-script		string	none	Path to a postuninstall script.
--install-check-script		string	none	Path to an install check script.
--uninstall-check-script		string	none	Path to an uninstall check script.
--config		bool	false	Run interactive configuration setup and exit.
--config-auto		bool	false	Auto-configure with defaults and exit.
--nointeractive		bool	false	Run with no prompts; use defaults or fail.
--emit-installs		bool	false	Print the auto-generated installs array as YAML to stdout and exit without importing.
--extract-icon		bool	false	Enable icon extraction from the installer. Experimental.
--icon		string	none	Custom icon output path when extraction is enabled.
--skip-icon		bool	false	Deprecated. Icon extraction is off by default; this prints a warning and is otherwise ignored.

Exit codes

Code	Meaning
0	Import succeeded, configuration setup succeeded, --emit-installs succeeded, or the user cancelled the import.
1	Configuration setup threw; no installer path supplied at the prompt; --emit-installs failed; import threw; parse error.

A cancelled import returning 0 is worth knowing before you wire this into CI.

cimiimport "C:\Installers\Firefox.msi" --arch x64

Preview the detection array a given installer would produce, without touching the repo:

cimiimport "C:\Installers\Firefox.msi" --emit-installs

---

cimipkg

Builds a deployable package from a project directory containing a build-info.yaml and a payload. MSI is the default output format. It embeds a base64 CIMIAN_PKG_BUILD_INFO blob and sets ARPSYSTEMCOMPONENT=1 on installer-type wrappers so the shim does not appear in Programs and Features.

cimipkg lives in its own repository and is consumed here as a git submodule (cli/cimipkg → windowsadmins/cimian-pkg). Its full flag set is documented there. The flags verified from this repository's own build and test code are:

Flag	Description
--verbose	Verbose output.
--skip-import	Suppress the post-build cimiimport prompt. Required in CI, where the prompt inherits stdio and hangs.
--create	Scaffold a new package directory with a build-info.yaml.
(positional)	The package source directory.

cimipkg --verbose --skip-import "C:\Projects\MyApp"

---

makepkginfo

Generates a pkgsinfo document for an installer and writes it to stdout — the counterpart of Munki's makepkginfo. The one exception is --new, which writes a stub file into the repository instead.

Positional argument: installer — the path to an MSI, EXE or NUPKG. Under --new the same positional is reinterpreted as the name of the pkginfo to create, not a path.

Unmatched tokens are an error. A readable configuration file must exist for the tool to start at all.

Scripts

Flag	Type	Description
--installcheck_script	string	Path to an install check script.
--uninstallcheck_script	string	Path to an uninstall check script.
--preinstall_script	string	Path to a preinstall script.
--postinstall_script	string	Path to a postinstall script.
--preuninstall_script	string	Path to a preuninstall script.
--postuninstall_script	string	Path to a postuninstall script.
--uninstaller	string	Path to an uninstaller executable. Emitted as a one-element uninstaller: list.

Metadata

Flag	Type	Default	Description
--catalogs	string	Development	Comma-separated catalog list.
--category	string	none	Category.
--developer	string	none	Developer.
--name	string	none	Package name override.
--identifier	string	none	Package identifier (nuspec id).
--displayname	string	none	Display name override.
--description	string	none	Description.
--pkg-version	string	none	Version override.
--minimum_os_version	string	none	Minimum Windows version required.
--maximum_os_version	string	none	Maximum Windows version supported.
--minimum_cimian_version	string	none	Minimum Cimian agent version required.

Behaviour

Flag	Type	Default	Description
--unattended_install	bool	false	Emit unattended_install: true.
--unattended_uninstall	bool	false	Emit unattended_uninstall: true.
--OnDemand	bool	false	Emit OnDemand: true for items that may run repeatedly. Case-sensitive flag name.
--new	bool	false	Create a new pkginfo stub rather than analysing an installer.
--file / -f	string list	none	Add extra files to the installs array. Repeatable.

Unused-software removal

Flag	Type	Description
--unused_removal_days	int	Emit unused_software_removal_info.removal_days: uninstall when no tracked executable has been used for this many days. Requires --unattended_uninstall and usage data.
--unused_path	string list	Emit an unused_software_removal_info.paths entry — an executable whose usage gates removal. Repeatable. Defaults to the .exe entries in installs.
--unused_minimum_history_days	int	Emit unused_software_removal_info.minimum_history_days: how many days of usage history a device must have before removal may act.

Exit codes

Code	Meaning
0	Success, including --new.
1	Configuration file not found; --new with no name or no configured repo path; neither an installer nor any -f supplied; installer file not found; any exception; parse error or unmatched token.

makepkginfo "C:\Installers\Firefox.msi" --catalogs Testing --category Browsers

---

makecatalogs

Scans pkgsinfo/ and writes the catalog files. Direct counterpart of Munki's makecatalogs. No subcommands, no positional arguments.

Flag	Aliases	Type	Default	Description
--repo_path	-repo_path, -r	string	falls back to repo_path in the config file	Path to the Cimian repository.
--skip_payload_check	-s	bool	false	Do not check that installer and uninstaller files exist.
--hash_check		bool	false	Enable hash validation. Slow. Size validation runs on every invocation and does not need this flag.
--silent	-q	bool	false	Minimise output.
--tolerate_parse_errors		bool	false	Write catalogs even if some pkgsinfo files fail to parse. Failing items are omitted.
-V		bool	false	Print version and exit. There is no --version long form.

The single-dash long alias -repo_path is a compatibility holdover and works.

Exit codes

Code	Meaning
0	Version printed, or catalog generation succeeded.
1	No repository path resolvable from the flag or the config; config file missing or unparseable; unhandled exception; parse error.

Other codes may be returned by the catalog builder itself.

makecatalogs --repo_path "\\fileserver\share\CimianRepo"

See Catalogs and Promotion.

---

manifestutil

Edits manifests in the repository, and handles self-service requests on a client. The counterpart of Munki's manifestutil, though it is flag-driven rather than interactive. No subcommands, no positional arguments.

Flag	Short	Type	Default	Description
--list-manifests	-l	bool	false	List available manifests.
--new-manifest	-n	string	none	Create a new manifest with this name.
--add-pkg	-a	string	none	Package to add to the manifest.
--remove-pkg	-r	string	none	Package to remove from the manifest.
--section	-s	string	managed_installs	Section to operate on: managed_installs, managed_uninstalls, managed_updates, optional_installs.
--manifest	-m	string	none	Manifest to operate on, without the .yaml extension. Required by --add-pkg and --remove-pkg.
--selfservice-request		string	none	Add a package to the local self-service manifest.
--selfservice-remove		string	none	Remove a package from the local self-service manifest.
--config	-c	string	the default config path	Path to the Cimian config file.
-V		bool	false	Print version and exit. There is no --version long form.

Actions are evaluated in a fixed order: -V, then the self-service flags, then the config load, then --list-manifests, --new-manifest, section validation, and finally --add-pkg / --remove-pkg. With no action flags at all it prints a help hint and returns 0.

The self-service paths write under C:\ProgramData\ManagedInstalls, so they need write access there; repository editing does not require administrator.

Exit codes

Code	Meaning
0	Any successful operation, the no-action help hint, and both self-service operations — which return 0 whether or not the package was actually added or removed.
1	repo_path not configured; manifests directory not found; --new-manifest name already exists; invalid --section; manifest file not found; any exception; parse error.

manifestutil --add-pkg Firefox --manifest site_default --section managed_installs

See Manifests.

---

repoclean

Prunes old package versions from the repository. Dry-run by default — nothing is deleted unless --remove is passed. No subcommands, no positional arguments.

Flag	Aliases	Type	Default	Description
--repo-url	-r	string	none, required in practice	Path to the Cimian repository. Despite the name it takes a filesystem path.
--keep	-k	int	2	Number of versions to keep per package.
--show-all	-a	bool	false	Show all packages, not just those that would be deleted.
--auto	-y	bool	false	Delete without prompting.
--remove	--delete	bool	false	Actually perform deletions.
-V		bool	false	Print version and exit. There is no --version long form.

Exit codes

Code	Meaning
0	Version printed, or a clean/dry-run completed.
1	--repo-url missing or empty; any exception during the run; parse error.

repoclean --repo-url "\\fileserver\share\CimianRepo" --keep 3

repoclean --repo-url "\\fileserver\share\CimianRepo" --keep 3 --remove --auto

See RepoClean for the analysis it performs and what counts as an orphan.

---

Related pages

• Installation — getting these binaries onto a machine
• Client Configuration — what the client reads before any of these flags apply
• Repository Layout — what the repository tools operate on
• Coming From Munki — the command-by-command mapping