CLI Reference

CLI reference

The command-line tool is managedstatekeeper.exe, installed at C:\Program Files\StartSet\managedstatekeeper.exe and added to the machine PATH by the installers. (The root command declares itself as startset in help text; the file on disk is managedstatekeeper.exe.)

Elevation is not requested by the manifest (asInvoker). Anything that touches C:\ProgramData\ManagedState or runs an elevated payload needs an elevated shell.

managedstatekeeper <command> [arguments] [options]

Global options

Option	Alias	Effect
--version	-V	Print the version as Major.MM.DD.HHMM and exit. Only honoured when it is the sole argument
--verbose	-v	Registered as a global option
--debug	-d	Registered as a global option
--help	-h, -?	Command help, from System.CommandLine

--verbose and --debug are declared but the log level is determined from Config.yaml alone — logging is initialised before the command line is parsed and no handler reads these options. To raise verbosity for a CLI run, set log_level: debug in Config.yaml. See Configuration.

Payload type tokens

Commands that take a payload type accept these, case-insensitively, with _ treated as - (so boot_once is equivalent to boot-once):

boot-once
boot-every
login-window
login-once
login-every
login-privileged-once
login-privileged-every
on-demand
on-demand-privileged

process additionally accepts ondemand-privileged as a spelling of on-demand-privileged. Anything else prints Unknown payload type and exits 1.

Execution commands

boot

Runs boot-once then boot-every, with no username, waiting for the network unless told not to.

Option	Alias	Effect
--skip-network	—	Skip the network wait regardless of wait_for_network

managedstatekeeper boot --skip-network

login

Runs login-once then login-every for a user. No network wait.

Option	Alias	Default	Effect
--user	-u	current user	Username used for run-once tracking and the ignored_users check

managedstatekeeper login --user jsmith

login-window

Runs login-window payloads. No options, no username, no network wait.

managedstatekeeper login-window

login-privileged

Runs login-privileged-once then login-privileged-every. Takes --user / -u as login does. Note that the run-once ledger for login-privileged-once is the system ledger regardless of the username passed — see Payload Directories.

managedstatekeeper login-privileged

on-demand

Runs on-demand payloads as the current user.

Option	Alias	Effect
--privileged	-p	Run on-demand-privileged instead

managedstatekeeper on-demand --privileged

process

Runs exactly one payload type. This is the command to reach for when reproducing a problem.

Argument / option	Alias	Effect
<type>	—	Payload type token (required)
--user	-u	Username for run-once tracking; defaults to the current user for user-context types, otherwise unset
--skip-network	—	Skip the network wait

The network wait only applies to boot-once here; every other type is processed without waiting regardless of the flag.

managedstatekeeper process login-every --user jsmith

cleanup

Deletes the four trigger files.

Option	Alias	Effect
--all	-a	Also delete every file in on-demand and on-demand-privileged

--all deletes on-demand payloads outright, whether or not they have run. It is a purge, not a tidy-up.

managedstatekeeper cleanup --all

Staging commands

add

Copies a file into a payload directory, overwriting an existing file of the same name.

Argument / option	Alias	Effect
<script>	—	Path to the source file (required, must exist)
--type	-t	Payload type token (required)
--checksum	-c	Record the SHA256 into share\checksums.yaml and print it

managedstatekeeper add .\Map-DepartmentDrives.ps1 --type login-every --checksum

add does not validate the extension against allowed_extensions; a file it copies in may still be ignored at run time.

remove

Deletes a file from a payload directory by name.

Argument / option	Alias	Effect
<script>	—	Filename to remove (required)
--type	-t	Payload type token (required)
--clear-runonce	—	Also clear the run-once entry, from both the system ledger and the current user's ledger

A missing file prints Script not found and still exits 0. --clear-runonce only does anything for run-once payload types.

managedstatekeeper remove Map-DepartmentDrives.ps1 --type login-once --clear-runonce

list

Lists payloads, grouped by payload type.

Option	Alias	Effect
--type	-t	Restrict to one payload type; omit for all
--show-executed	-e	Add an Executed column for run-once types
--json	-j	Emit JSON instead of a table

--show-executed computes each file's checksum and asks the ledger, so it reflects the same "edited scripts re-run" rule the engine uses: a changed script shows as not executed. For user-context types it consults the ledger of the user running the command.

JSON records carry PayloadType, FileName, FilePath, Size and, with --show-executed, Executed.

managedstatekeeper list --type login-once --show-executed

managedstatekeeper list --json

Ignored users

Manage the ignored_users list in Config.yaml. All three write through the preferences serializer.

Command	Arguments	Notes
add-ignored-user	one or more usernames	Lowercased before storing; already-present names are reported and skipped
remove-ignored-user	one or more usernames	Case-insensitive match; names not present are reported
list-ignored-users	—	Prints the list sorted

managedstatekeeper add-ignored-user kioskuser svc_backup

managedstatekeeper remove-ignored-user kioskuser

Overrides

Manage the overrides list — payloads that re-run even when the run-once ledger says they have already run.

Command	Arguments / options	Notes
add-override	one or more script paths or filenames	Reduced to the lowercased filename before storing
remove-override	one or more script paths or filenames	See options below
list-overrides	—	Prints the list sorted

remove-override options:

Option	Alias	Effect
--clear-runonce	-c	Also delete the run-once ledger entry for the script
--user	-u	Which user's ledger --clear-runonce targets; omit for the system ledger

managedstatekeeper add-override Set-DefaultAppAssociations.ps1

managedstatekeeper remove-override Set-DefaultAppAssociations.ps1 --clear-runonce --user jsmith

Checksums

checksum

Argument / option	Alias	Effect
<file>	—	Path to a file, or the literal all
--record	-r	Write the checksum(s) into share\checksums.yaml
--comment	-c	Comment stored with the recorded entry

With a path, prints <sha256> <filename>. With all, walks every payload directory, filters to allowed_extensions, and prints <sha256> <fullpath> per file with #-prefixed header and total lines.

managedstatekeeper checksum "C:\ProgramData\ManagedState\boot-every\Configure-Firewall.ps1"

managedstatekeeper checksum all --record --comment "Baseline for spring image"

Recording checksums does nothing on its own — set checksum_validation: true in Config.yaml to have them enforced.

Exit codes

Code	Meaning
0	Success
1	A payload failed, an argument was invalid, an operation errored, or an unhandled exception was caught

Only ExecutionStatus.Failed — a payload that ran and returned non-zero — feeds the non-zero exit code from an execution command. A payload that timed out, was deferred because the user session could not be reached, was skipped for a failed permission or checksum check, or had an unsupported extension, does not raise the exit code. Do not use the exit code as your only health signal; read reports\items.json, which distinguishes these. See Logging and Reporting.

An MSI payload returning 3010 (restart required) is treated as success.

Recipes

Re-run a login-once payload for one user without editing it:

managedstatekeeper remove-override Set-Wallpaper.ps1 --clear-runonce --user jsmith

Trigger on-demand payloads through the service rather than the CLI, so they run in the console user's session:

New-Item -ItemType File 'C:\ProgramData\ManagedState\.startset.ondemand' -Force

Arm login-privileged-once for the next logon:

New-Item -ItemType File 'C:\ProgramData\ManagedState\.startset.login-privileged' -Force

Take a checksum baseline after staging a set of payloads:

managedstatekeeper checksum all --record