OSManagerCLI Command Line & Exit Codes

Note

This reference is for advanced users who want to automate it or interpret an exit code.

Command-line (headless) use

As well as double-clicking the .exe and walking through its interactive menus, OSManagerCLI can run a ‘hands-free’ reimage as part of one of your automation scripts, straight from the command line:

.\OSManagerCLI.exe -PreIngestedOSFileHandle 'gx3p_25Q3_f0885a6e' -MachineToReimageHandle 'gx3p-42123'

You can tell if a reimage was successful or not by checking the exit code (0 means success).

.\OSManagerCLI.exe -PreIngestedOSFileHandle 'gx3p_25Q3_f0885a6e' -MachineToReimageHandle 'gx3p-42123'
$reimageSuccessExitCode = $LASTEXITCODE

if( $reimageSuccessExitCode -eq 0 ) {
  Write-Host "Reimage Was Successful"
}
else {
  $exitCodesMeaning = & .\OSManagerCLI.exe -DescribeExitCode $reimageSuccessExitCode
  Write-Host "Reimage Failed with Exit Code $reimageSuccessExitCode, which means: $exitCodesMeaning"
}

OSManagerCLI requires Administrator rights, so it relaunches itself in a new elevated window if you are not already running in a Terminal ‘(As Administrator)’. If you are in a non-elevated session, to capture its exit code from a script, start it elevated and wait for it to finish:

$run = Start-Process .\OSManagerCLI.exe `
  -ArgumentList '-PreIngestedOSFileHandle','gx3p_25Q3_f0885a6e','-MachineToReimageHandle','MYSERVER' `
  -Verb RunAs -Wait -PassThru

$reimageSuccessExitCode = $run.ExitCode   # 0 = success; see the tables below
Write-Host "Exit Code Was: $reimageSuccessExitCode"

Parameters

Parameter	Description
-IngestOSFilePath <path>	Ingest the OS image at <path> (an .iso or .os file) into your OS Library.
-PreIngestedOSFileHandle <handle>	Use an OS you’ve already ingested, identified by its handle (the name shown in the OS list). Requires -MachineToReimageHandle.
-MachineToReimageHandle <hostname>	The server (Actor) to reimage. Requires an OS source: one of the two parameters above must be set.
-Help	Print usage for every parameter, then exit.
-Version	Print just the version number of the current .exe (e.g. 1.12), for easy scripting, then exit.
-DescribeExitCode <n>	Print the name and meaning of a single exit code, then exit.
-ListExitCodes	Print the full exit-code table, then exit.

A few rules the tool enforces:

• -IngestOSFilePath and -PreIngestedOSFileHandle can’t be used together. They’re two ways of choosing the same thing.
• -MachineToReimageHandle needs an OS source as well.
• -PreIngestedOSFileHandle needs -MachineToReimageHandle.

Examples

# Ingest an OS only
OSManagerCLI.exe -IngestOSFilePath "D:\OSImages\gx3p_25Q3_f0885a6e.iso"

# Reimage a server using an OS you've already ingested
OSManagerCLI.exe -PreIngestedOSFileHandle gx3p_25Q3_f0885a6e -MachineToReimageHandle MYSERVER

# Ingest an OS and reimage a server in one go
OSManagerCLI.exe -IngestOSFilePath "D:\OSImages\gx3p_25Q3_f0885a6e.iso" -MachineToReimageHandle MYSERVER

Exit codes

OSManagerCLI returns a meaningful exit code so that scripts (and you) can tell exactly how a run ended. 0 means success; anything else indicates why it stopped.

Tip

Run OSManagerCLI.exe -ListExitCodes (or -DescribeExitCode <n>) at any time to print this information directly from the tool.

Success

Code	Name	Meaning
0	Success	Completed successfully, or you quit normally.

Command-line parameters (100–199)

Code	Name	Meaning
100	ParamMutuallyExclusiveSources	-IngestOSFilePath and -PreIngestedOSFileHandle were both supplied (use only one).
101	ParamMachineHandleNeedsOsSource	-MachineToReimageHandle was supplied without an OS source.
102	ParamPreIngestedHandleNeedsMachine	-PreIngestedOSFileHandle was supplied without -MachineToReimageHandle.

Start-up & environment (200–299)

Code	Name	Meaning
200	ConfigInvalidJson	The config file contains invalid JSON.
201	NoDeploymentShareFolderSelected	No OS Library (deployment share) folder was selected.
202	DeploymentShareSetupFailedAsAdmin	Deployment share setup failed while running as Administrator.
203	DeploymentShareSetupNeedsAdmin	Deployment share setup is incomplete and needs Administrator rights.
204	SevenZipMissingUserDeclined	7-Zip wasn’t found and you chose not to continue without it.
205	D3ServiceMissingUserDeclined	d3Service wasn’t detected and you chose not to continue without it.
206	PasswordProtectedSharingGuestMissing	Password Protected Sharing couldn’t be disabled (the built-in Guest account wasn’t found).
207	PasswordProtectedSharingUserDeclined	You declined to disable Password Protected Sharing (which requires enabling the Guest account).
208	GuestNetworkAccessPolicyUndetermined	Couldn’t determine the Windows Guest network-access policy.
209	GuestNetworkAccessUserDeclined	You declined the Windows policy change that lets servers reach the deployment share on your laptop.
210	LocalD3ServiceVersionTooLow	The d3/Designer version installed on this machine is below the minimum required.
211	D3InstalledButServiceNotRunning	d3/Designer is installed on this machine but the d3Service process isn’t running, so the local API is unreachable.

OS selection, headless (300–399)

Code	Name	Meaning
300	HeadlessOsHandleNotFound	The pre-ingested OS handle wasn’t found in your OS Library.
301	HeadlessOsLibraryEmpty	Your OS Library is empty (nothing has been ingested yet).

Ingesting an OS, headless (400–499)

Code	Name	Meaning
400	HeadlessIngestSevenZipPathNotSet	The 7-Zip path isn’t set in the config.
401	HeadlessIngestSevenZipPathInvalid	The configured 7-Zip path doesn’t exist.
402	HeadlessIngestArchiveUnreadable	7-Zip couldn’t read the archive (invalid or corrupt file).
403	HeadlessIngestNotEnoughDiskSpace	Not enough disk space to extract the archive.
404	HeadlessIngestCreateDirFailed	Couldn’t create the OS Library destination folder.
405	HeadlessIngestExtractionFailed	7-Zip returned an error while extracting the archive.
406	HeadlessIngestNotExactlyTwoWims	The archive didn’t contain exactly two .wim files.
407	HeadlessIngestNotExactlyOneBootWim	The archive didn’t contain exactly one boot .wim file.
408	HeadlessIngestOsDirNotExactlyOneWim	The /OS folder didn’t contain exactly one .wim file.
409	HeadlessIngestSourcesDirNotExactlyOneBootWim	The /sources folder didn’t contain exactly one boot .wim file.
410	HeadlessIngestOsWimMoveFailed	Couldn’t move the OS .wim into the OS Library.
411	HeadlessIngestBootWimMoveFailed	Couldn’t move the boot .wim into the OS Library.
412	HeadlessIngestFileNotFound	The file given to -IngestOSFilePath doesn’t exist.

Redisguise / reimage, headless (500–599)

Code	Name	Meaning
500	HeadlessRedisguiseNoServerSelected	No server was selected.
501	HeadlessRedisguiseNoOsSelected	No OS was selected.
502	HeadlessRedisguiseEndpointNotVerified	Couldn’t resolve and identity-verify the server’s d3Service API endpoint. DNS-SD discovery and the last-known address were both tried; the intended machine couldn’t be confirmed on a reachable IP and port.
505	HeadlessRedisguiseNoOsWim	No OS .wim file was found in the selected OS.
506	HeadlessRedisguiseNoBootWim	No boot .wim file was found in the selected OS.
507	HeadlessRedisguiseReimageRequestFailed	The reimage request failed.
509	HeadlessRedisguiseDesignerVersionTooLow	The server’s installed Designer version is below the minimum required, and headless mode can’t prompt to override.
510	HeadlessRedisguiseActorHasRunningProject	The server has a project open in Designer, and headless mode can’t prompt to override.
511	HeadlessRedisguiseMultipleBootWims	The OS profile contains more than one boot .wim, and headless mode can’t prompt to pick which one to use.

Redisguise USB, headless (600–699)

Code	Name	Meaning
600	HeadlessUsbNoOsSelected	No OS was selected for Redisguise USB creation.