Docs / Automate / Command Line

Command Line

Automate NTLite from the command line - load images, save, export, create ISOs, apply changes, and download updates.

Many NTLite operations can be driven from the command line for scripting and unattended automation - loading an image, saving or exporting, creating an ISO, applying changes, and downloading updates. Command-line runs go through the same processing pipeline and the same license checks as the interface.

Switches use the Windows /Switch form, with values passed after a colon - for example /Index:1 or /Save:Stop. The same list is printed by running ntlite.exe /? in the app, which is the authoritative reference; this page mirrors it.

Multi-instance control: with NTLite already running, a command routes into that instance and controls it, rather than starting a throwaway process. Use /NewInstance to start a separate, independent process instead.

For scripts: run NTLCLI.exe from the NTLite folder with the same switches: it waits for the command to finish, prints its progress, asks NTLite's questions on the console and returns one of the exit codes below.

Scripting with NTLCLI

PowerShell, cmd, CI runners and remote sessions (Ansible, OpenSSH) treat NTLCLI.exe like any console tool: the call blocks until the job ends, each status line streams to the console or to a redirected output, and $LASTEXITCODE / %ERRORLEVEL% carries the result. Calling ntlite.exe directly still works, but a shell gets its prompt back at once; with its output captured (a pipe, Python, a CI step) it prints the same status lines.

NTLCLI.exe /Source:"D:\Win11" /Index:1 /Preset:"D:\my.xml" /Apply /Exit:AfterApply

  • NTLite open or closed: the command goes to the running NTLite, or NTLCLI starts one first. The window stays open afterwards unless the command carries /Exit.
  • Questions: a question NTLite asks during the command shows in the NTLite window and on the console at the same time, and the first answer, from either side, closes the other. Type the key shown in brackets; an empty line asks again. Checkboxes and checklist ticks can be changed only in the window.
  • Nobody to answer: with no console to type in (input redirected or closed), each question takes its safe answer (No or Cancel), the log records it, and the run ends with exit code 9. Notices with only an OK button print to the console and the run goes on.
  • Ctrl+C: cancels the running operation and returns its real result; at a question it answers Cancel.
  • Updates: while a command runs, a newer NTLite is reported on the console only; run NTLCLI.exe /Update to install it.

Without administrator rights

NTLite itself always runs elevated. From a console without administrator rights, NTLCLI starts NTLite through the usual elevation prompt, and its first command asks Allow command-line access? in the NTLite window, naming the program that started NTLCLI. An Allow is remembered for that program and Windows account, and is listed in Settings, under Security, where it can be removed; a No refuses that program until NTLite closes (exit code 8).

  • An allowed program edits image files freely, but never runs programs on this computer or another installed Windows: a command with Post-Setup items, post-apply commands or .reg imports for an installed Windows is refused whole before anything changes (exit code 8), and the console names each refused item.
  • Command prompts, script hosts and other programs that start programs for others ask once more, each time NTLite starts, before their first change to an installed Windows.
  • For unattended machines, Allow command-line access without asking in Settings, under Security, or /Trust on NTLite's own command line, lets NTLCLI without administrator rights in with no prompt. Any program running as you can then control NTLite, so use it only where that is acceptable, such as a test machine.

With no visible window

Over OpenSSH, from a service or from a task that runs whether the user is logged on or not, the NTLite window cannot be seen. Licensed editions run there unattended; questions go to the console as above. The free edition refuses every command there with exit code 10, since its prompts can only be answered in the window; /Exit and /Cancel still work.

Usage

A typical invocation combines a source, an optional preset, and an action:

ntlite.exe /Source:"[image path]" /Load /Index:[X] /Preset:"[preset]" /Apply /Save[:Save|Stop] /Discard /Export /ImageFormat:[wim|esd|swm] /SplitSize:[MB] /RemoveEditions:[i,j|All] /CreateIso /Dest:"[destination]" /Merge /IsoLabel:"[ISO label]" /DownloadUpdates:"[options]" /ThreadMax:[threads] /Exit:AfterApply

For unattended scripting, the process exits with code 0 on success and a non-zero code on failure, and writes a single NTLite: <verb> SUCCESS or NTLite: <verb> FAILED line to the log for each action.

Source

Select and open an image to work on.

  • /Source:"..." - path to an image or an extracted image folder (WIM, ESD or SWM; extract an ISO to a folder first; also /Src, or /Path as older scripts write it).
  • /Index:N - image edition index to select within the image.
  • /Load - mount if needed and load the selected image for editing.
  • /Preset:"..." (Optional) - name of the preset in the Presets directory or a direct preset file path (repeat to combine several).

Process

Saving, format, edition, ISO, and apply options. These mirror the Image Options dialog and the Apply page, where the same choices are documented in full.

  • /Apply - start applying pending tasks.
  • /Save[:Save|Stop] (Optional) - saving mode, bare /Save equals /Save:Save. Save - save the image; Stop - Keep image mounted (stop before saving the loaded and install images, boot and recovery still save; requires /Apply).
  • /Discard - unload the image, discarding the in-memory changes without saving.
  • /ImageFormat:[wim|esd|swm] (Optional) - output container. wim is the standard format, ready for mounting and editing; esd is high-compression read-only (not supported on Windows 7 or boot/WinRE images); swm splits the image to bypass the FAT32 single-file 4 GB limit or span across multiple media (also /Format).
  • /SplitSize:[MB] (Optional) - SWM part size in MB (requires /ImageFormat:swm).
  • /RemoveEditions:[i,j|All] (Optional) - remove editions (1-based index list, comma-separated, or All for every edition that can be removed; requires /Save or /Export, and /Apply to change /ImageFormat in the same run).
  • /Export (Optional) - export the /Source image as it is on disk, or the one edition /Index names, to /Dest; loaded or not, never unmounts; no /Apply.
  • /CreateIso (Optional) - create ISO, to /Dest. No /Apply needed - without /Source it builds the loaded image; a /Source naming the loaded image applies its pending changes first, any other /Source builds as-is.
  • /Dest:"..." (Optional) - the file /Export or /CreateIso writes (also /Destination).
  • /Merge (Optional) - add to an existing /Dest image instead of overwriting it.
  • /IsoLabel:"..." (Optional) - ISO label (up to 32 characters; requires /CreateIso).
  • /Exit (Optional) - close a running NTLite. Bare /Exit closes it if idle (refused while busy); /Exit:Now cancels any in-flight work and closes immediately; /Exit:AfterApply closes after the operation completes. The legacy /ExitAfter:[0|1] still parses as an alias of /Exit:AfterApply.
  • /Cancel - abort the running operation and keep NTLite open. Mirrors the GUI Cancel button and is the escape from a Busy refusal.

Note: /Save:Stop keeps the mount live for a later session, while /Discard throws the edits away and releases the image. /Export always writes a copy and never modifies the loaded image; splitting straight to a separate destination (/ImageFormat:swm with /Export) is not supported - split in place instead.

Updates

  • /DownloadUpdates:"..." Premium (Optional) - download and integrate Windows updates for the loaded image. Takes a comma-separated list of update types, applied where relevant to the loaded image:
  • All
  • Default - Recommended
  • CU - Cumulative Update
  • PCU - Preview Cumulative Update
  • DE - Defender Engine Update
  • DP - Defender Platform Update
  • DU - Dynamic Setup Update
  • EP - Enablement Package
  • ESU
  • NCU - .NET Framework Cumulative Update
  • NHU - .NET Framework Hotfix
  • NF - .NET Framework
  • PS - PowerShell
  • SafeOS
  • Terminal
  • VCLibs
  • VCLibsU
  • WaRun - Windows Application Runtime 1.8
  • WaRun2 - Windows Application Runtime 2.0.*
  • Winget
  • WSL
  • XAML
  • OOBE

Other

  • /ThreadMax:N (Optional) - maximum number of CPU threads to use. Useful in multi-instance scenarios to limit CPU usage.
  • /NewInstance Premium (Optional) - force a fresh independent process instead of routing the command to an already-running instance.
  • /Trust - let NTLCLI run without administrator rights control this NTLite with no prompt, until it closes. Taken from NTLite's own command line or an elevated NTLCLI only.
  • /Forget - remove the /Source image, folder or ISO from the image history list. Standalone maintenance only; it does not delete anything from disk.
  • /Delete - delete the /Source image edit folder from disk. Standalone.
  • /Revert - throw away every change made in the /Source image edit folder (or an image in it) and make it match its reference image again, copying or deleting only what differs. Standalone; refused while the edit is mounted or other edits were made from it.
  • /Rename:"..." - give the /Source folder, ISO or image file a new name, where the Image page offers Rename; the extension stays. Standalone.
  • /Refresh - read the image list again from disk. Standalone.
  • /Update - check if there is a newer version of this tool available, and install it; NTLite closes for the installer. Standalone; needs no other NTLite open and no image loaded. While a command-line command runs, NTLite never updates on its own: it prints Update available and waits for /Update.
  • /? - command-line parameters, printed to the console when run from one (or with output redirected, e.g. ntlite.exe /? > help.txt), else shown in a window; also shown on a syntax error.

Examples

The full example shown by ntlite.exe /?:

ntlite.exe /Source:"D:\Test\WinEdit" /Load /Index:3 /Preset:"Main Preset" /Preset:"Additional Common Settings" /DownloadUpdates:"CU,NCU,Winget" /CreateIso /Dest:"D:\WinEdit.ISO" /IsoLabel:"WinUpdated" /ThreadMax:6 /Apply /Exit:AfterApply

Common single-purpose runs:

  • Image load: ntlite.exe /Source:"D:\Win11" /Load /Index:1
  • Apply: ntlite.exe /Source:"D:\Win11\sources\install.wim" /Index:1 /Preset:"D:\my.xml" /Apply /Save
  • Apply, convert to ESD, and build an ISO: ntlite.exe /Source:"D:\Win11" /Index:1 /Apply /ImageFormat:esd /CreateIso /Dest:"D:\Win11.iso" /IsoLabel:"WIN11"
  • Build an ISO from an image folder, without loading it: ntlite.exe /Source:"D:\Win11" /CreateIso /Dest:"D:\Win11.iso" /IsoLabel:"WIN11"
  • Image export, one edition to a new ESD file: ntlite.exe /Source:"D:\src.wim" /Index:2 /Export /Dest:"D:\one.esd" /ImageFormat:esd
  • Remove Reinstalls: ntlite.exe /CleanCU
  • Force listing of undetected components: ntlite.exe /ForceListComponents
  • Forget a history entry: ntlite.exe /Source:"D:\old.wim" /Forget
  • Install an available update: NTLCLI.exe /Update

Exit codes

The same numbers come from NTLCLI.exe and ntlite.exe, and keep their meaning across releases.

  • 0 - succeeded
  • 1 - failed (also: nothing to cancel, image or preset not found)
  • 2 - busy with other work, try again when idle
  • 3 - NTLite stopped answering
  • 4 - could not reach NTLite
  • 5 - several NTLite windows are open, close all but one (or use /NewInstance)
  • 6 - NTLCLI: NTLite could not be started (missing, or the elevation prompt was declined)
  • 7 - NTLCLI: NTLite started but did not accept the command in time
  • 8 - not allowed: a caller without administrator rights was declined, or asked for what needs them
  • 9 - a question came up and nobody could answer it; it took its safe answer
  • 10 - free edition with no visible window: the command line needs a Premium license
Scheduled TasksUnattended