PatchWork Documentation

1 — Introduction

PatchWork is a command-line tool for managing Windows Updates. It talks directly to the Windows Update Agent (WUA) via COM, which means there is no .NET runtime dependency, ensuring the binary is self-contained and compact. The tool covers the full update lifecycle: searching for available updates, downloading them, installing them, uninstalling them, and generating structured reports.

Why PatchWork?

The built-in Windows update management only covers part of the problem. wuauclt.exe and UsoClient.exe trigger background scans and installs but give no feedback and no filtering. PSWindowsUpdate is a capable PowerShell module but requires .NET and PowerShell execution policy consideration on some builds. PatchWork sits in the gap. It runs from a Windows console, script, via remote execution (PSExec etc.), or via a scheduled task under SYSTEM. It accepts fine-grained filtering via the command line, and exits with a code that scripts can branch on.

Key Features

• Full search, download, install, uninstall, and history operations for Windows Update, Microsoft Update, or via a WSUS server.
• Classification and severity filtering, KB number allow/deny lists, regex title matching, product filtering, size caps, release date windows, and update ID filtering — combinable in a single invocation.
• XML and JSON report output for downstream processing, SIEM ingestion, or compliance tooling.
• Email (SMTP) and syslog notifications after each run.
• Persistent default options stored in the registry, with per-run override capability.
• Pre- and post-operation custom actions (batch, PowerShell, or any other executable).
• Windows Update system health check that probes the environment to confirm the environment is working as required.

Intended Audience

This document is aimed at Windows system administrators, MECM(SCCM)/Intune engineers, and anyone automating patch management via scripts, DevOps or scheduled tasks. A working knowledge of Windows Update concepts (WSUS, WUA, classifications, KB articles) is assumed throughout.

2 — System Requirements and Prerequisites

Operating System

PatchWork runs on Windows 7 and later, including all Windows Server editions from Server 2008 R2 onward. Both 32-bit and 64-bit platforms are supported. Official support is only provided for Windows versions that are within Microsoft's Active Support window.

Privileges

Most operations — download, install, uninstall, and anything that touches WSUS registry settings — require administrative privileges. Run PatchWork from an elevated Command Prompt, as a scheduled task under the SYSTEM account, or via runas. The --search, --history, --installed, and --healthcheck operations can run without elevation, though certain checks within --healthcheck will report reduced information if admin is unavailable.

Network

For Windows Update and Microsoft Update sources, outbound HTTPS to Microsoft's update endpoints must be reachable. For WSUS, the machine must be able to reach the WSUS server on its configured port (typically 8530 for HTTP, 8531 for HTTPS). SMTP and syslog notification features need outbound access to the configured mail or log server.

Disk Space

There is no fixed disk space requirement for PatchWork itself. The binary is small. Update download and installation vary by patch content; use --check-available-disk-space to verify free space before a large run.

3 — Installation and Removal

Quick Install

Run PatchWork once with --setup from an elevated prompt:

patchwork --setup

This copies the running executable to C:\Program Files\Emerita\Patchwork\, adds that directory to the System PATH environment variable, and writes an installation record to HKLM\SOFTWARE\Emerita\Patchwork. After setup, patchwork is available from any Command Prompt without specifying the full path (a new shell session, or a refreshenv, is needed for the PATH change to take effect in existing sessions).

Custom Install Path

To install to a different directory, pass the desired path as an argument:

patchwork --setup "D:\Tools\PatchWork"

Recommended Install

Register and provide default settings during install. You can apply a sensible set of defaults via --opt-verbose, or provide custom settings tailored to your environment via --opt-save. A registered install can be as simple as:

patchwork.exe --setup --register "FirstName LastName/Companyname|XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX" --opt-verbose

To provide custom settings that suit your particular environment:

patchwork.exe --setup --register "FirstName LastName/Companyname|XXXXX-..." --opt-save --autoaccepteula --ignore-errors --logfile c:\windows\temp\patchwork.log --show-progress --color --info --hide-sensitive --wsus-server http://wsusserver.internal.pri

Running Without Installing

PatchWork does not require installation. The executable can be placed anywhere on the file system and run directly. --setup is a convenience that handles PATH registration; it is not a prerequisite.

Upgrading

Running --setup when PatchWork is already installed performs an upgrade rather than a fresh install. It compares the version of the running binary against the version recorded in the registry and, if the running binary is newer, copies it over the installed copy.

patchwork --setup

Uninstalling

patchwork --remove

This removes the installed executable, deletes the installation directory, removes the PATH entry, and deletes HKLM\SOFTWARE\Emerita\Patchwork. Administrator privileges are required.

Verifying the Installation

patchwork --version
patchwork --healthcheck

--version prints the version string. --healthcheck probes the environment more thoroughly to determine if the Windows Updater Agent API is working as expected.

4 — Licensing and Registration

Interactive Registration

patchwork --register

Prompts for a username and serial number, then stores the license. No other arguments are needed.

Unattended Registration

Pass the credentials on the command line, separated by a pipe character:

patchwork --register "FirstName LastName/Companyname|XXXXX-XXXXX-XXXXX-XXXXX"

The argument must be quoted if it contains spaces. This form is suitable for deployment scripts where interactive input is not available.

Combining Registration with Other Operations

--register can be combined with --setup and other configuration operations in a single invocation:

patchwork --setup --register "FirstName LastName/Companyname|XXXXX-XXXXX-XXXXX-XXXXX" --opt-save --use-windowsupdate

License Storage

License data is managed by the Obsidium licensing system. If you receive a false positive from your AV solution, please exclude patchwork.exe from scanning, contact your AV vendor directly to whitelist the executable, or contact us so we can contact the AV vendor on your behalf.

Unlicensed Versions

If you are not a registered customer and are not using an evaluation version, PatchWork will report an unlicensed state on startup, provide limited functionality, and exit any operations with code 8 (InvalidVersion). No update operations are performed.

5 — Concepts and Terminology

Update Sources

PatchWork obtains updates from one of three sources.

• Windows Update (WU) — Microsoft's public update service for Windows. This is the default source when no WSUS server is detected in the registry.
• Microsoft Update (MU) — A superset of Windows Update that also distributes updates for other Microsoft products such as Office. Register it once with --register-microsoftupdate, or force it for a single run with --use-microsoftupdate.
• WSUS — Windows Server Update Services, the enterprise update proxy. When WSUS is configured on a machine (via Group Policy, MECM/SCCM or the registry), PatchWork will use it by default. You can override this with --use-windowsupdate or --use-microsoftupdate, or point to a specific server with --wsus-server.

Update Classifications

The --classification switch accepts a string of single-letter codes:

Codes are combined without separators. --classification CU limits results to Critical and Security updates.

Update Severities

The --severity switch accepts single-letter codes representing the MSRC severity rating:

The Search–Download–Install Lifecycle

PatchWork separates the three stages of update deployment. Running --install performs all three internally (search, then download, then install). Running --search alone lets you review what is available before committing. Running --download stages updates to the local WUA cache without installing; a subsequent --install will use the cached copies.

Default Options and Precedence

PatchWork supports a saved set of default options stored in the registry under HKLM\Software\Emerita\Patchwork as the DefaultOptions value. These are automatically prepended to the command line on every run. CLI arguments always take precedence over saved defaults. Use --opt-ignore on any individual run to bypass the saved defaults for that run without deleting them.

Exit Codes

PatchWork exits with a numeric code that scripts can branch on. The most commonly used codes are:

• 0 — success, no reboot needed
• 1 — at least one error, no reboot needed
• 3 — no updates matched the filter criteria
• 10 — success, but one or more updates require a reboot

See Section 9 for the full table.

6 — Quick Start

The following examples assume PatchWork is installed and patchwork is in PATH. Run from an elevated Command Prompt unless noted otherwise.

Check what updates are available:

patchwork --search --info

Search for Critical and Security updates only:

patchwork --search --classification CU --info

Download Critical and Security updates without installing:

patchwork --download --classification CU

Install Critical and Security updates, reboot automatically if required:

patchwork --install --classification CU --autoaccepteula --reboot-if-needed

Install all updates, log to file, no console output:

patchwork --install --autoaccepteula --silent --logfile C:\Logs\updates.log

Check the environment before running:

patchwork --healthcheck

7 — Command Reference

Options are grouped here as they appear in --help. One operation flag is required per invocation unless the command is a management-only action (--register, --setup, --remove, --opt-save, --opt-clear, --opt-show, --opt-verbose, --list-exit-codes, --healthcheck).

7.1 — Operations

These flags determine what operation PatchWork performs. Exactly one primary operation must be present per invocation, unless the operation is a management-only action.

--search

Search queries the configured update source for available updates without downloading or installing anything. Apply any filter switches alongside --search to narrow the results. Combine with --info to provide full update details, or with --xmlout/--jsonout to produce a report.

patchwork --search --classification CU --info
patchwork --search --releasedate days:30 --jsonout C:\Reports\pending.json

--download

Searches for updates matching the active filters and downloads them to the Windows Update local cache. The updates are ready to install on a subsequent --install run.

patchwork --download --classification CU --severity CI

--install

Searches for matching updates, downloads any that are not already cached, and installs them. This is the most commonly used operation for a standard patching run.

patchwork --install --classification CU --autoaccepteula --reboot-if-needed

--uninstall

Removes previously installed updates. Combine with --kb, --match-filter, or --match-id to target specific updates. Not all updates support uninstallation; PatchWork will report which ones are uninstallable before proceeding.

patchwork --uninstall --kb KB5012345

--history

Lists the Windows Update installation history — the equivalent of Settings → Windows Update → Update History.

patchwork --history --xmlout C:\Reports\history.xml

--installed

Lists updates currently installed on the system — the equivalent of Settings → Apps → Installed Updates.

patchwork --installed --jsonout C:\Reports\installed.json

--register ["USER|KEY"]

Registers the product license. Without arguments it will prompt interactively. With the "USER|KEY" argument, it registers unattended. See Section 4.

--setup [PATH]

Installs PatchWork and adds it to the System PATH. Defaults to C:\Program Files\Emerita\Patchwork if no path is given. Requires administrator privileges. See Section 3.

--remove

Uninstalls PatchWork. Removes the executable, directory, PATH entry, and registry keys. Requires administrator privileges.

7.2 — Update Type Selection

By default, PatchWork searches for software updates only. These switches change that scope.

--driveronly

Restricts the search to driver updates. Mutually exclusive with --includedrivers.

patchwork --search --driveronly --info

--includedrivers

Adds driver updates to the software update search. Mutually exclusive with --driveronly.

patchwork --install --includedrivers --classification CUV

--alltypes

Includes all update types that the WUA supports. Useful when auditing a machine.

patchwork --search --alltypes --info

--preview

Includes preview, optional, and beta updates, which are hidden from the default search. Use with care in production environments. Note: this option is not available on Windows versions prior to Windows 10 1903 and Windows Server 2022.

patchwork --search --preview --info

7.3 — Search Criteria and Filtering

When multiple filters are active, an update must satisfy all of them (AND logic). Within the --kb and --match-id switches, multiple values use OR logic.

--criteria CRITERIA

Passes a raw WUA search criteria string directly to the Windows Update Agent. Overrides PatchWork's default criteria construction.

patchwork --search --criteria "IsInstalled=0 AND Type='Software' AND IsHidden=0"

--classification FLAGS

Filters updates by classification category. Pass one or more letter codes as a single string without separators. See Section 5.

patchwork --install --classification CU          # Critical and Security
patchwork --install --classification CUDISRF     # All software, no drivers
patchwork --search  --classification CUDISRFEVG  # Everything

--severity FLAGS

Filters updates by MSRC severity rating. See Section 5.

patchwork --install --severity CI    # Critical and Important only
patchwork --search  --severity CIML  # All rated updates
patchwork --search  --severity U     # Updates with no severity rating

--product PRODUCTS

Includes only updates that belong to a matching product or category. Accepts a comma-separated list of substrings (case-insensitive substring match against WUA category names).

patchwork --search --product "Windows 10"
patchwork --search --product "Windows 11,Office"

--exclude-product PRODUCTS

Excludes updates that match any of the listed product substrings.

patchwork --install --exclude-product "Windows Defender"
patchwork --install --exclude-product "Office,Silverlight"

--kb KB_NUMBERS

Filters by KB article number. Accepts a comma-separated list. Prefix a KB number with - to exclude it. The KB prefix is optional. When include entries are present, only those specific updates pass. When only exclude entries are present, everything except the excluded KBs passes.

patchwork --install --kb KB5078740               # Include one KB
patchwork --install --kb KB5078740,KB5034441     # Include two KBs
patchwork --install --kb KB5078740,-KB5034441    # Include one, exclude another
patchwork --search  --kb -KB5034441              # Exclude one KB, show all others

--match-filter PATTERN

Applies a regex pattern to update titles and descriptions. Standard .NET-compatible regex syntax applies.

patchwork --search --match-filter "Cumulative Update.*2025"
patchwork --search --match-filter "(?i)security"         # Case-insensitive
patchwork --search --match-filter "Windows (10|11)"

--nomatch-filter PATTERN

Excludes updates whose title or description matches the regex pattern.

patchwork --install --nomatch-filter "Preview|Beta"
patchwork --install --nomatch-filter "Defender"

--matchfile FILE

Loads include patterns from a text file, one regex pattern per line. Lines beginning with # are comments. Multiple patterns are combined with OR logic.

patchwork --install --matchfile C:\Config\critical-kbs.txt

--nomatchfile FILE

Loads exclude patterns from a text file. Same format as --matchfile. Multiple patterns are combined with OR logic.

patchwork --install --nomatchfile C:\Config\excluded-kbs.txt

--matchfile and --nomatchfile can be combined with each other and with --match-filter/--nomatch-filter in the same run.

--releasedate DATE

Filters updates by their release date. Accepted formats:

patchwork --search --releasedate days:30
patchwork --search --releasedate ge:2025-01-01
patchwork --install --releasedate gt:2025-03-01

Updates with no release date recorded by WUA are always excluded when this filter is active.

--max-update-count COUNT

Caps the number of updates that will be processed in a single run. Applied after all other filters. Useful for staged rollouts.

patchwork --install --classification CU --max-update-count 10

--max-total-size SIZE

Caps the cumulative size of updates that will be processed. Accepts a numeric value with an optional suffix: K, M, G, or T (or two-letter variants KB, MB, GB, TB).

patchwork --download --max-total-size 500M
patchwork --download --max-total-size 2G

--match-id IDS

Filters by update GUID. Accepts a comma-separated list. Prefix a GUID with - to exclude it. Matching is case-insensitive.

patchwork --install --match-id 9fb049d9-8ee3-4913-937f-196648006ca5
patchwork --install --match-id ID1,ID2,-ID3

--only-downloaded

Restricts results to updates that have already been downloaded to the local WUA cache.

patchwork --install --only-downloaded --autoaccepteula

7.4 — Configuration Options

These switches configure the update source and related service settings. Most write temporarily to the registry and are restored when PatchWork exits. --register-microsoftupdate and --clear-wsus-server make permanent changes.

--register-microsoftupdate

Registers the Microsoft Update service with the local Windows Update Agent, enabling updates for all Microsoft products (Office, Visio, etc.) in addition to Windows updates. This change persists after PatchWork exits. Only needs to be run once per machine. Requires administrator privileges.

--clear-wsus-server

Removes the WSUS server configuration from the registry, causing the machine to fall back to Windows Update. This is a permanent change. Requires administrator privileges.

--use-wsus

Forces the use of WSUS as the update source, even if another source was saved as a default. Primarily useful to restore WSUS as the source after a --use-windowsupdate or --use-microsoftupdate default has been saved.

--use-windowsupdate

Bypasses WSUS and queries Windows Update directly. Applied for the duration of the current run only.

patchwork --search --use-windowsupdate

--use-microsoftupdate

Queries the Microsoft Update service directly, bypassing WSUS. Includes Office and other Microsoft product updates. Applied for the current run only.

--wsus-server SERVER

Temporarily points PatchWork at a specific WSUS server URL for the current run. The machine's existing WSUS registry configuration is restored on exit.

patchwork --install --wsus-server http://wsus.corp.example.com:8530
patchwork --install --wsus-server https://wsus.corp.example.com:8531

--use-mu-on-error

If the WSUS server is unreachable, fall back to Microsoft Update for the current run.

--use-wu-on-error

If the WSUS server is unreachable, fall back to Windows Update for the current run.

--targetgroup GROUP

Sets the WSUS client-side target group for the current run. The registry is restored to its original state when PatchWork exits.

patchwork --install --targetgroup "Production_Servers"
patchwork --install --wsus-server http://wsus.example.com:8530 --targetgroup "Pilot"

--notargetgroup

Removes the WSUS target group registry entries before the operation, so the machine is treated as ungrouped for this run. The original values are restored on exit.

7.5 — Proxy Configuration

Proxy settings are applied for the duration of the current run and restored on exit. Currently WinHTTP proxies are supported. SOCKS proxies are NOT supported.

--disable-win-http-proxy

Disables the WinHTTP proxy for this run.

--disable-ie-proxy

Disables the Internet Explorer proxy for this run.

--auto-detect-proxy

Enables WPAD (Web Proxy Auto-Discovery) via IE's AutoDetect setting.

--proxy-address ADDRESS

Specifies a proxy server address manually.

patchwork --search --proxy-address proxy.corp.example.com --proxy-port 8080

--proxy-port PORT

Specifies the proxy server port. Requires --proxy-address.

7.6 — Reboot and Shutdown Options

At most one of --reboot, --reboot-if-needed, --shutdown, or --shutdown-if-needed may be specified per invocation.

--reboot

Initiates a system reboot immediately after the operation completes, regardless of whether the installed updates require one. Returns exit code 5 on success, 6 on failure.

--reboot-if-needed

Initiates a reboot only if one or more installed updates report that a reboot is required.

patchwork --install --classification CU --autoaccepteula --reboot-if-needed

--shutdown

Shuts the system down after the operation instead of rebooting.

--shutdown-if-needed

Shuts the system down if any installed update requires a reboot; exits normally otherwise.

--force-close

Forces applications to close before the reboot or shutdown proceeds. Use with care: applications will not have an opportunity to save data.

--delay SECONDS

Pauses for the specified number of seconds before initiating a reboot or shutdown.

patchwork --install --reboot-if-needed --delay 300   # 5-minute warning

--reboot-message MESSAGE

Displays the specified message in the Windows shutdown dialog before a reboot or shutdown.

patchwork --install --reboot-if-needed --delay 300 --reboot-message "Rebooting for monthly security updates in 5 minutes."

--rebootcycle COUNT

Enables automatic reboot cycling. After installing updates, if a reboot is required and the cycle count has not been exhausted, PatchWork registers itself to run again on the next startup and then reboots. The cycle counter is stored in the registry and decremented on each resume.

patchwork --install --classification CU --rebootcycle 3 --max-update-count 20

7.7 — Installation Options

--autoaccepteula

Automatically accepts End User License Agreements without prompting. Required for unattended operation.

--force

Forces re-download and re-installation of updates, including those already installed or already cached.

--ignore-errors

Continues processing remaining updates if one download or install fails, rather than aborting the run. The exit code will still reflect that errors occurred. Recommended for production use.

patchwork --install --ignore-errors --logfile C:\Logs\updates.log

--defender-fix

If a Microsoft Defender Antivirus signature update fails during an --install run, automatically attempts a recovery by removing stale definition files and triggering a fresh download and install.

patchwork --install --defender-fix
patchwork --install --classification CUD --defender-fix

--parallel-downloads N

Sets the number of concurrent downloads (1–10). Default is 3.

patchwork --download --parallel-downloads 5
patchwork --download --parallel-downloads 1   # serialise for bandwidth-limited links

7.8 — Logging and Reporting

--quiet

Reduces console output to essential results only. Progress details, per-update listings, and informational banners are suppressed. Error messages and final counts are still shown.

--silent

Suppresses all console output. Pair with --logfile to preserve a record.

patchwork --install --silent --logfile C:\Logs\nightly.log

--logfile FILE

Writes all output to the specified file in addition to the console.

patchwork --install --logfile "C:\Logs\updates.log"

--logmode MODE

Controls log file behaviour when the file already exists. overwrite (default) truncates the file before writing. append adds to the existing content.

patchwork --install --logfile C:\Logs\updates.log --logmode append

--logencoding ENCODING

Sets the character encoding for the log file. Unicode (default) writes UTF-16LE. ANSI writes plain text with the system code page.

--xmlout FILE

Writes a structured XML report to the specified path on completion.

patchwork --search --xmlout C:\Reports\scan.xml

--xmlout-with-bom

Adds a UTF-8 BOM to the XML output file. Required for correct rendering in some spreadsheet applications (Excel).

--jsonout FILE

Writes a structured JSON report to the specified path on completion.

patchwork --search --jsonout C:\Reports\scan.json

--info

Prints detailed information about each update — title, KB article, classification, severity, size, release date, and description.

--show-progress

Displays per-update download and installation progress on the console. Useful for interactive sessions; omit for scheduled tasks.

--color

Enables ANSI color output. Requires a terminal that supports VT escape sequences (Windows Terminal, modern ConHost etc.).

--extended-error

Changes exit code semantics to a bitmap combining multiple status flags. See Section 9.

--simple-error

Collapses exit codes to 0 (success) or 1 (any error).

--debug

Enables structured debug tracing. Writes a full JSON span log to %TEMP%\patchwork-debug-<pid>.log. Primarily for diagnostics and support bundle generation.

--hide-sensitive

Redacts sensitive values (--smtp-user, --smtp-password, --register) in console output and log files.

--list-exit-codes

Prints a table of all exit codes and their meanings, then exits.

patchwork --list-exit-codes
patchwork --list-exit-codes --jsonout C:\Reports\codes.json

--healthcheck

Runs a series of environment checks — administrator privilege status, WUA service availability, COM class registration, WSUS connectivity (if configured), disk space, pending reboot state, proxy configuration, and recent update timestamps. Exits with code 0 if all checks pass, code 1 if any check fails.

patchwork --healthcheck
patchwork --healthcheck --xmlout C:\Reports\health.xml

7.9 — Timeout and Runtime

--maxruntime SECONDS

Sets a hard upper limit on total execution time. If the limit is exceeded before the operation completes, PatchWork exits with code 12 (TimeoutReached).

patchwork --install --maxruntime 3600   # Allow up to 1 hour

--retrycount COUNT

Number of retry attempts for failed search, download, or install operations. Retries use an exponential backoff with jitter (initial delay 2 seconds, maximum delay 30 seconds).

patchwork --install --retrycount 5

--noretry

Disables automatic retry entirely. PatchWork will fail immediately on the first error.

7.10 — Custom Actions

Custom actions run synchronously under the same account token as PatchWork itself. The working directory is inherited from the parent process.

Dispatch logic:

• If the command's first token ends in .ps1, the script is run as: powershell.exe -ExecutionPolicy Bypass -NonInteractive -File <path> [args]
• All other commands are run as: cmd.exe /C <command>

If a custom action exits with a non-zero code, PatchWork logs the failure but continues.

--custom-action-before COMMAND

Runs a command before the main operation begins.

patchwork --install --custom-action-before "net stop MyAppService"
patchwork --install --custom-action-before "C:\Scripts\pre-patch.ps1"
patchwork --install --custom-action-before "net stop Svc1 & net stop Svc2"

--custom-action-after COMMAND

Runs a command after the main operation completes, regardless of outcome.

patchwork --install --custom-action-after "net start MyAppService"
patchwork --install --custom-action-after "C:\Scripts\post-patch.ps1 -SendReport"

7.11 — System Checks

--check-available-disk-space DRIVE[:SIZE]

Reports the free space on the specified drive. Accepts the drive letter with or without a colon or backslash (C, C:, C:\ are all equivalent). An optional minimum free-space requirement can be appended directly after the drive letter (e.g. C:10G). If the available free space is less than the specified size, PatchWork exits immediately before any other operation.

patchwork --check-available-disk-space C:
patchwork --check-available-disk-space C:10G
patchwork --install --check-available-disk-space C:500M --classification CU

--refresh-last-update-timestamps

Writes the current date and time to the Windows Update timestamp registry entries (LastSearchTime, LastDownloadTime, LastInstallTime, LastUninstallTime, LastCheckTime).

patchwork --refresh-last-update-timestamps

7.12 — Default Options Management

Default options are stored as a string in the registry at HKLM\Software\Emerita\Patchwork under the value DefaultOptions. On every run, PatchWork reads this string, prepends it to the actual command line, and parses the combined result. Explicitly supplied command-line arguments always override saved defaults.

--opt-save

Saves the saveable options from the current command line as the new persistent defaults. Not all switches are saved — operation flags, reboot flags, and management flags are excluded. Requires administrator privileges (writes to HKLM).

patchwork --opt-save --use-windowsupdate --autoaccepteula --logfile C:\Logs\patchwork.log

--opt-clear

Removes the saved defaults from the registry.

--opt-show

Prints the currently saved default options string without running any operation.

--opt-ignore

Skips loading the saved defaults for this run. The registry value is not modified.

patchwork --install --opt-ignore --use-windowsupdate

--opt-verbose

Applies a preset that enables the following useful options: --autoaccepteula --ignore-errors --logfile %TEMP%\patchwork.log --show-progress --color --info --hide-sensitive. When used without a primary operation, saves the preset as the default options. When combined with a primary operation, applies it for that run only.

patchwork --opt-verbose --install --classification CU   # Run with verbose preset
patchwork --opt-verbose                                  # Save verbose preset as defaults
patchwork --opt-verbose --install --logfile D:\log.log   # Verbose, but override logfile

8 — Output Formats and Reporting

Console Output

Log Files

Log files capture the same content as the console at the selected verbosity level. Encoding defaults to UTF-16LE (Unicode); use --logencoding ANSI for plain text. Mode defaults to overwrite; use --logmode append to accumulate across runs.

XML Output

The XML report generated by --xmlout contains a root <PatchWorkReport> element with a <Summary> section and an <Updates> collection. Each <Update> element includes:

• <Title> — update title
• <KBArticleID> — KB number
• <Classification> — update classification
• <Severity> — MSRC severity
• <Size> — download size in bytes
• <ReleaseDate> — YYYY-MM-DD
• <Description> — full update description
• <UpdateID> — WUA GUID

Add --xmlout-with-bom to prefix the file with a UTF-8 BOM for Excel compatibility.

JSON Output

The JSON report generated by --jsonout follows the same logical structure as the XML output, with a top-level summary object and an updates array.

Debug Trace

--debug produces a structured JSON span log at %TEMP%\patchwork-debug-<pid>.log. The file contains timestamped event records covering every major operation. Send it alongside the regular log file when reporting an issue.

Sample XML Report

<?xml version="1.0" encoding="utf-8"?>
<PatchWorkReport>
  <Summary>
    <TotalUpdates>3</TotalUpdates>
    <TotalSize>314572800</TotalSize>
    <Operation>install</Operation>
    <Status>Success</Status>
  </Summary>
  <Updates>
    <Update>
      <Title>2025-04 Cumulative Update for Windows 10 Version 22H2</Title>
      <KBArticleID>KB5036893</KBArticleID>
      <Classification>Security Updates</Classification>
      <Severity>Critical</Severity>
      <Size>209715200</Size>
      <ReleaseDate>2025-04-08</ReleaseDate>
      <UpdateID>9fb049d9-8ee3-4913-937f-196648006ca5</UpdateID>
    </Update>
  </Updates>
</PatchWorkReport>

9 — Exit Codes

Standard Exit Codes

Extended Exit Codes (--extended-error)

When --extended-error is active, the exit code is a bitmap combining the following flags:

Parsing in PowerShell:

$code = $LASTEXITCODE
if ($code -band 0x10) { Write-Host "Reboot required" }
if ($code -band 0x08) { Write-Host "max-update-count was hit; more updates may remain" }
if ($code -band 0x01) { Write-Host "A Windows Update error occurred" }

Parsing in CMD:

patchwork --install --extended-error --max-update-count 5 --classification CU
set /a REBOOT_REQ=%ERRORLEVEL% ^& 16
if %REBOOT_REQ% GTR 0 echo Reboot required

Using Exit Codes in Scripts

patchwork --install --classification CU --autoaccepteula --reboot-if-needed
if %ERRORLEVEL% EQU 0  echo All done, no reboot needed.
if %ERRORLEVEL% EQU 10 echo Install succeeded - rebooting now.
if %ERRORLEVEL% EQU 3  echo No matching updates found.
if %ERRORLEVEL% EQU 1  echo Install completed with errors.
if %ERRORLEVEL% EQU 12 echo Timed out before all updates were installed.

10 — Deployment Scenarios

Standalone Workstation Using Windows Update

patchwork --install --classification CU --severity CI ^
  --autoaccepteula --reboot-if-needed --delay 60 ^
  --logfile "C:\Logs\patch-%DATE:~10,4%%DATE:~4,2%%DATE:~7,2%.log"

Run from a scheduled task under SYSTEM, daily or weekly, during off-hours.

Domain-Joined Client Using WSUS

If the machine is already Group Policy-targeted at a WSUS server, PatchWork will use it automatically.

patchwork --install --classification CU --autoaccepteula ^
  --targetgroup "Production_Desktops" ^
  --reboot-if-needed --logfile C:\Logs\update.log

Add --use-wu-on-error to fall back to Windows Update if the WSUS server is temporarily unreachable.

Server Core and Headless Deployments

patchwork --install --classification CU --autoaccepteula ^
  --silent --logfile C:\Logs\update.log ^
  --xmlout C:\Reports\update.xml ^
  --reboot-if-needed
if %ERRORLEVEL% EQU 10 shutdown /r /t 300

Running Under SYSTEM via Task Scheduler

Create a scheduled task with:

• Action: patchwork.exe --install --classification CU --autoaccepteula --silent --logfile C:\Logs\patch.log --reboot-if-needed
• Run as: SYSTEM
• Run with highest privileges: Yes
• Trigger: Weekly, outside business hours

SCCM/MECM Package or Script Deployment

patchwork --install --classification CU --autoaccepteula --ignore-errors ^
  --quiet --logfile "%TEMP%\patchwork-mecm.log"
exit /b %ERRORLEVEL%

MECM treats exit code 0 as success and any other code as failure. If updates require a reboot (exit code 10), configure the deployment to handle a soft reboot.

Intune Win32 App Deployment

• Install command: patchwork.exe --install --classification CU --autoaccepteula --ignore-errors --quiet
• Return codes: 0 = Success, 10 = Success with reboot (map to Intune code 3010), 3 = No updates found (map to Success), 1 = Failure

Staged Pilot Rollout

rem Phase 1: Download on pilot machine
patchwork --download --classification CU --logfile C:\Logs\pilot-download.log

rem Phase 2: Install on pilot
patchwork --install --classification CU --autoaccepteula ^
  --logfile C:\Logs\pilot-install.log --xmlout C:\Reports\pilot.xml ^
  --reboot-if-needed

rem Phase 3: After validation, deploy broadly

Citrix and RDS Gold Image Patching

Patch the gold image before sealing. Repeat until --search returns exit code 3 (no updates remaining).

:loop
patchwork --install --classification CU --autoaccepteula --quiet ^
  --xmlout C:\Temp\patch-result.xml
if %ERRORLEVEL% EQU 10 (
    shutdown /r /t 0
)
if %ERRORLEVEL% EQU 0 goto done
if %ERRORLEVEL% EQU 3 goto done
echo Errors during patching - review C:\Temp\patch-result.xml
:done

11 — Automation and Scripting Patterns

Parsing JSON Output in PowerShell

patchwork --search --classification CU --jsonout "$env:TEMP\scan.json" | Out-Null
$report = Get-Content "$env:TEMP\scan.json" | ConvertFrom-Json

foreach ($update in $report.updates) {
    Write-Host "$($update.title) — $($update.kbArticleId) — $($update.size) bytes"
}

Write-Host "Total: $($report.summary.totalUpdates) updates"

Handling Exit Codes in PowerShell

patchwork --install --classification CU --autoaccepteula --reboot-if-needed
switch ($LASTEXITCODE) {
    0  { Write-Host "All updates installed. No reboot needed." }
    10 { Write-Host "Updates installed. Rebooting in 5 minutes."; Start-Sleep 300; Restart-Computer -Force }
    3  { Write-Host "No updates matching filter." }
    1  { Write-Error "Install completed with one or more errors." }
    12 { Write-Error "Timed out. Some updates may not have been installed." }
    default { Write-Error "Unexpected exit code: $LASTEXITCODE" }
}

Saving Site-Wide Defaults

patchwork --opt-save --use-windowsupdate --autoaccepteula ^
  --logfile C:\Logs\patchwork.log --logmode append ^
  --xmlout C:\Reports\patchwork.xml --hide-sensitive

After this, a simple patchwork --install --classification CU will automatically include all those options. Override any saved default by specifying it explicitly on the command line.

Pre/Post Custom Actions for Service Control

patchwork --install --classification CU ^
  --custom-action-before "net stop MyAppService & net stop MyDBService" ^
  --custom-action-after  "net start MyDBService & net start MyAppService" ^
  --autoaccepteula --logfile C:\Logs\patch.log

Idempotent Reboot Handling

patchwork --search --classification CU --severity CI
if %ERRORLEVEL% EQU 3 (
    echo No updates pending. Done.
    exit /b 0
)

patchwork --install --classification CU --severity CI ^
  --autoaccepteula --reboot-if-needed ^
  --logfile C:\Logs\startup-patch.log

Banding Pilot Rings with Count and Date Limits

rem Ring 1: install up to 5 updates released more than 30 days ago
patchwork --install --classification CU ^
  --releasedate le:2025-03-01 --max-update-count 5 ^
  --autoaccepteula --logfile C:\Logs\ring1.log

12 — Filtering Examples

Security Updates Only, Last 30 Days:

patchwork --search --classification U --releasedate days:30 --info

Critical and Security Updates, Critical and Important Severity:

patchwork --install --classification CU --severity CI --autoaccepteula

Everything Except a Specific KB:

patchwork --install --kb -KB5034441

All Software Updates Except Definitions:

patchwork --install --classification CUISRF --autoaccepteula

Cumulative Updates by Regex:

patchwork --search --match-filter "Cumulative Update for Windows" --info

Driver Updates from a Specific Vendor:

patchwork --search --driveronly --product "Intel" --info
patchwork --install --driveronly --product "NVIDIA" --autoaccepteula

Load a Curated KB Allow-list from a File:

approved-kbs.txt example:

# Monthly approved patches - approved 2025-05-01
KB5078740
KB5034441
KB5036893

patchwork --install --matchfile C:\Config\approved-kbs.txt --autoaccepteula

Combining Multiple Filters:

patchwork --install ^
  --classification CU ^
  --severity CI ^
  --match-filter "Windows (10|11|Server 2022)" ^
  --releasedate ge:2025-01-01 ^
  --nomatch-filter "Preview" ^
  --max-update-count 20 ^
  --autoaccepteula

How Filters Interact

Filters are applied in this order:

1. WUA query (default IsInstalled=0)
2. Classification filter (--classification)
3. Severity filter (--severity)
4. KB include/exclude list (--kb)
5. Update ID include/exclude list (--match-id)
6. Regex include (--match-filter or --matchfile)
7. Regex exclude (--nomatch-filter or --nomatchfile)
8. Product include (--product)
9. Product exclude (--exclude-product)
10. Only-downloaded filter (--only-downloaded)
11. Preview filter (excluded unless --preview)
12. Release date filter (--releasedate)
13. Size cap (--max-total-size) — applied cumulatively
14. Count cap (--max-update-count) — truncates the final list

An update must pass all active filters. If no filters are specified for a given dimension, that dimension is not filtered.

13 — Notifications

Email Notifications

PatchWork can send an email report after any primary operation. Required: --smtp-server, --email-from, at least one --email-to, and --send-email-on-completion.

Port and Encryption matrix:

Authenticated SMTP example:

patchwork --install --classification CU ^
  --smtp-server smtp.corp.example.com --smtp-port 587 ^
  --smtp-encryption starttls ^
  --smtp-user patchwork@corp.example.com ^
  --smtp-password "secretpassword" ^
  --email-from patchwork@corp.example.com ^
  --email-to sysadmin@corp.example.com ^
  --email-subject "Patch Run Complete — %COMPUTERNAME%" ^
  --send-email-on-completion ^
  --hide-sensitive

Specify --email-to more than once for multiple recipients. If --email-subject is not specified, PatchWork uses PatchWork <operation> Report - <status> as the default subject.

Saving email configuration as defaults:

patchwork --opt-save ^
  --smtp-server smtp.corp.example.com ^
  --smtp-port 587 --smtp-encryption starttls ^
  --smtp-user svc-patchwork@corp.example.com ^
  --smtp-password "password" ^
  --email-from svc-patchwork@corp.example.com ^
  --email-to ops-team@corp.example.com ^
  --send-email-on-completion --hide-sensitive

Syslog Notifications

PatchWork sends a single RFC-5424 syslog message after each operation. Default transport is UDP.

patchwork --install --classification CU ^
  --syslog-server siem.corp.example.com ^
  --syslog-port 514 ^
  --syslog-protocol udp ^
  --syslog-facility local0 ^
  --syslog-tag patchwork ^
  --send-syslog-on-completion

Use --syslog-protocol tcp if your SIEM requires reliable delivery. PatchWork supports local0 through local7. Severity mapping:

14 — Security Considerations

Privilege Model

PatchWork follows the principle of least privilege. --search, --history, --installed, and --healthcheck do not require elevation. All operations that write to the registry or modify the system require administrator privileges.

Credential Handling

• SMTP passwords passed via --smtp-password appear in the command line and may be captured in process listings. Use --hide-sensitive to redact them in PatchWork's own log output. Consider storing the SMTP configuration as saved defaults via --opt-save. The saved value is stored in the registry under HKLM\Software\Emerita\Patchwork — ensure the SMTP account has minimal permissions.
• License keys passed via --register are similarly sensitive. --hide-sensitive redacts the --register argument in logs.

What --hide-sensitive Covers

The following switch values are replaced with ******** in all console output and log files:

• --smtp-user
• --smtp-password
• --register

Code Signing

The PatchWork executable is digitally signed with an Authenticode certificate issued to Chad Matthieson. Verify the signature before deploying:

Get-AuthenticodeSignature "C:\Program Files\Emerita\Patchwork\patchwork.exe"

PatchWork contains code to ensure the digital signature is present and correct prior to operation execution. If PatchWork does not launch correctly, redownload and replace the executable.

Registry Keys

Hardening on Shared Hosts

15 — Performance and Tuning

Parallel Downloads

The --parallel-downloads switch controls how many updates are downloaded concurrently. Default of 3 is a reasonable middle ground. On fast LAN connections, values up to 6 or 8 may improve throughput. On metered or low-bandwidth links, set it to 1 to serialise downloads. Note: parallel installation is NOT possible via the Windows Update Agent API.

patchwork --download --parallel-downloads 1 --classification CU   # Low bandwidth
patchwork --download --parallel-downloads 6 --classification CU   # Fast LAN

Bounding Run Time

In scheduled task environments where the task window is fixed, set --maxruntime to prevent PatchWork from running past the end of the maintenance window:

patchwork --install --classification CU --maxruntime 3600 --autoaccepteula

Reducing Scope to Improve Speed

rem Routine: Critical and Security only
patchwork --install --classification CU --severity CI

rem Monthly audit: everything
patchwork --search --alltypes --classification CUDISRFEVG --xmlout C:\Reports\audit.xml

WSUS Load

High --parallel-downloads values combined with a large --max-update-count can generate significant load on a WSUS server when run on many devices in parallel. Consider staggering start times or reducing parallelism. PatchWork's exponential-backoff retry logic (--retrycount) handles transient WSUS server busy conditions gracefully.

16 — Troubleshooting

Run --healthcheck First

Before investigating a failed update run, run --healthcheck. It identifies the most common problems — missing WUA service, insufficient disk space, WSUS unreachable, pending reboot blocking installation — in a single pass.

patchwork --healthcheck
patchwork --healthcheck --xmlout C:\Reports\health.xml

No Updates Found (exit code 3)

The most common causes:

1. All matching updates are already installed. Run with --history to confirm.
2. Filter too narrow. Try broadening --classification or removing --severity.
3. Wrong update source. If pointing at WSUS, the WSUS server may not have approved updates for this machine. Try --use-windowsupdate to compare.
4. Target group mismatch. If WSUS is configured with client-side targeting, the machine may be in a group with no approved updates.

WUA COM Errors (0x800401F0)

This error means the Windows Update Agent COM class is not registered. The WUA service may be corrupted or disabled.

net stop wuauserv
regsvr32 /s %windir%\system32\wuapi.dll
regsvr32 /s %windir%\system32\wuaueng.dll
net start wuauserv

WSUS Connectivity Issues

Verify the WSUS server URL and port:

Test-NetConnection -ComputerName wsus.corp.example.com -Port 8530

Use --use-windowsupdate as a diagnostic bypass. If updates succeed via Windows Update but fail via WSUS, the issue is WSUS-side.

Proxy Issues

• Try --disable-win-http-proxy or --disable-ie-proxy to check whether the proxy is the cause.
• Try --auto-detect-proxy to see if WPAD resolves correctly.
• Use --debug to capture proxy negotiation detail in the trace log.

Operation Timeout (exit code 12)

Increase --maxruntime or reduce the scope of the run (fewer updates per pass, lower --parallel-downloads).

Common WUA HRESULT Codes

Collecting a Support Bundle

To assist with a support request, collect the following:

1. The regular log file (--logfile output).
2. The debug trace (--debug output from %TEMP%\patchwork-debug-<pid>.log).
3. The XML or JSON report from the failing run.
4. The output of patchwork --healthcheck --xmlout C:\Reports\health.xml.
5. The output of patchwork --opt-show (to confirm the active defaults).
6. The .dmp file if automatically generated.

Send the resulting output to support@emerita.dev.

17 — Comparison and Migration

PatchWork vs Built-in Tools

Migrating from PSWindowsUpdate

Migrating from WuInstall

WuInstall users will find many switch names familiar. Key differences:

• PatchWork uses --search, --download, --install, --uninstall as explicit operation flags rather than positional arguments. The / switch prefix is not available.
• Classification codes largely match but PatchWork adds E (Driver Sets), V (Drivers), and G (Upgrades).
• Output formats (XML and JSON) are richer and include per-update descriptions.
• Default options are stored in the registry via --opt-save rather than a configuration file.

18 — Appendices

Appendix A — Sample Scheduled Task XML

Weekly Sunday 02:00 task that runs PatchWork under SYSTEM:

<?xml version="1.0" encoding="UTF-16"?>
<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
  <Triggers>
    <CalendarTrigger>
      <StartBoundary>2025-01-05T02:00:00</StartBoundary>
      <ScheduleByWeek>
        <WeeksInterval>1</WeeksInterval>
        <DaysOfWeek><Sunday /></DaysOfWeek>
      </ScheduleByWeek>
    </CalendarTrigger>
  </Triggers>
  <Principals>
    <Principal>
      <UserId>S-1-5-18</UserId>
      <RunLevel>HighestAvailable</RunLevel>
    </Principal>
  </Principals>
  <Actions>
    <Exec>
      <Command>C:\Program Files\Emerita\Patchwork\patchwork.exe</Command>
      <Arguments>--install --classification CU --severity CI --autoaccepteula --reboot-if-needed --delay 300 --silent --logfile C:\Logs\weekly-patch.log --xmlout C:\Reports\weekly-patch.xml</Arguments>
    </Exec>
  </Actions>
</Task>

Import with: schtasks /create /xml "task.xml" /tn "PatchWork Weekly"

Appendix B — Sample PowerShell Deployment Script

$date       = Get-Date -Format 'yyyyMMdd'
$logFile    = "C:\Logs\patch-$date.log"
$reportFile = "C:\Reports\patch-$date.xml"

Stop-Service -Name "MyAppService" -ErrorAction SilentlyContinue

patchwork --install `
    --classification CU `
    --severity CI `
    --autoaccepteula `
    --ignore-errors `
    --reboot-if-needed `
    --delay 300 `
    --silent `
    --logfile $logFile `
    --xmlout $reportFile

$result = $LASTEXITCODE

Start-Service -Name "MyAppService" -ErrorAction SilentlyContinue

switch ($result) {
    0  { Write-EventLog -LogName Application -Source PatchWork -EventId 1000 -Message "Patching complete, no reboot." }
    10 { Write-EventLog -LogName Application -Source PatchWork -EventId 1001 -Message "Patching complete, reboot scheduled." }
    3  { Write-EventLog -LogName Application -Source PatchWork -EventId 1002 -Message "No updates found." }
    default {
        Write-EventLog -LogName Application -Source PatchWork -EventId 1099 -EntryType Warning `
            -Message "Patching finished with unexpected code $result. See $logFile."
    }
}

exit $result

Appendix C — Glossary

Appendix D — Registry Keys

WSUS and proxy configuration keys are modified temporarily during operations and restored on exit.