Migrating from winrm4j

Why migrate

• Zero runtime dependencies. winrm4j pulls in the Apache CXF stack — dozens of jars, roughly 10 MB — plus whatever JAXB/JAX-WS additions your JDK requires. This client is a single jar of a few hundred kB that speaks WS-Management over the JDK's own HTTP and XML APIs.
• Modern JDKs, no workarounds. The library targets Java 11 and runs on any later JDK — no jakarta/javax juggling, no JAXB add-ons.
• Immune to JAXP conflicts by construction. It uses the JDK-default XML factories directly, so another library's ServiceLoader-registered XML implementation cannot break it — a classic winrm4j/CXF failure mode.
• Actively maintained, with releases published on Maven Central.
• Features winrm4j never had: WQL / WMI queries^[2], file transfers^[3] through the WinRM channel, standard input^[4], Process-style streaming^[5] of live output, and a full-featured command-line client^[6].

The five-minute version

// winrm4j
WinRmTool tool = WinRmTool.Builder.builder("server.example.com", "DOMAIN\\Administrator", "password")
    .authenticationScheme(AuthSchemes.NTLM)
    .port(5985)
    .useHttps(false)
    .build();
WinRmToolResponse response = tool.executeCommand("ipconfig /all");
System.out.println(response.getStdOut());
System.out.println(response.getStatusCode());

becomes:

// WinRM Java Client
try (WinRMClient client = WinRMClient.builder("server.example.com")
        .credentials("DOMAIN\\Administrator", "password".toCharArray())
        .build()) {
    CommandResult result = client.command("ipconfig /all").execute();
    System.out.println(result.stdout());
    System.out.println(result.exitCode());
}

NTLM over HTTP on port 5985 is the default on both sides, so nothing needs to be spelled out. Two shape differences are visible immediately:

• The client is AutoCloseable and meant for try-with-resources — it authenticates once and runs any number of commands and queries over the same connection, where winrm4j re-created a shell (and re-authenticated) on every executeCommand(...) call.
• The password is a char[], not a String; the builder takes the array as-is, without copying it.

Option mapping

Behavioral differences

Beyond the API shapes, a few runtime behaviors differ deliberately. Worth reading before flipping the switch:

• Payload encryption is always on over HTTP. In winrm4j, NTLM message encryption is a configurable PayloadEncryptionMode (OFF / OPTIONAL / REQUIRED) that only appeared in its final 0.12.x releases. Here, HTTP always uses NTLM message encryption — there is no unencrypted mode and nothing to configure, and hosts that require encryption (AllowUnencrypted=false, the Windows default) work out of the box.
• Basic needs HTTPS, but the client does not enforce it. winrm4j offers AuthSchemes.BASIC, which here maps to authentication(AuthScheme.BASIC). This client has no Basic message protection: it accepts the scheme over both transports, so use https() with it — without TLS, the credential and payload travel in the clear and the client will not stop you. The host must have the Basic setting enabled on the WinRM service and be reachable over HTTPS (Preparing the Windows Host^[15]). NTLM remains the recommended scheme.
• Kerberos requires HTTPS. winrm4j runs Kerberos over plain HTTP; this client refuses at build(), because it does not implement Kerberos message encryption — without TLS the payload would travel unprotected. Connect with https() and by the FQDN the KDC knows (Authentication^[8]).
• TLS certificates are validated by default, including hostname verification — like winrm4j (disableCertificateChecks exists on both sides), but worth re-checking if your winrm4j setup disabled checks and you want to stop doing that: point sslContext(...) at a trust store containing the host certificate instead (TLS / HTTPS^[9]).
• Command output is UTF-8, not code page 437. winrm4j hardcodes WINRS_CODEPAGE=437 (US-OEM), which mangles any non-ASCII output on non-English hosts. This client creates the remote shell with code page 65001 (UTF-8), so accented and non-Latin output decodes correctly whatever the remote locale — no configuration needed (Character encoding^[16]).
• Timeout semantics. winrm4j's operationTimeout is the WSMan Receive polling timeout (how long each poll waits for output), and separate CXF settings govern connect/receive at the HTTP level. Here a single timeout(Duration) (default 30 s) is a wall-clock deadline for the whole operation with execute(), and an inactivity timeout with start() (Timeouts and Errors^[14]).
• No silent retries. winrm4j retries connection failures once by default and can be told to retry Receive after an operation timeout. Here nothing is retried unless you opt in with retries(int, Duration), and the policy is deliberately narrow: only attempts that provably never reached the server (TCP connect, DNS, TLS handshake, the authentication handshake) are retried, preserving at-most-once execution for non-idempotent commands. A request that was actually sent is never replayed.
• One shell per client. winrm4j creates and tears down a remote shell for every executeCommand(...). This client creates the shell on the first command and reuses it, which is faster — and is why workingDirectory(...) and environment(...) are per-command options that take effect on the client's first command (command options^[10]).

What you gain

Once on the fluent API, features winrm4j never offered are one call away:

• WQL / WMI queries — client.wql("SELECT Name, State FROM Win32_Service").execute(), with typed rows and streaming (WQL Queries^[2]).
• File transfers — upload(Path...) copies local scripts to the host through the WinRM channel itself (no SMB, no port 445) before the command runs (File Transfers^[3]).
• Standard input — stdin(...) feeds a remote command its input, with real EOF semantics (Standard input^[4]).
• Live streaming — start() returns a java.lang.Process-shaped RemoteProcess^[17] whose output is consumed while the command runs, with bounded memory (Streaming the output^[5]).
• A real CLI — the standalone jar runs commands, PowerShell, WQL queries, and an interactive remote shell from the terminal (Command-Line Client^[6]).

See also

• Installation^[18] — coordinates and supported JDKs
• Remote Commands^[19] — the complete command API
• Authentication^[8] — NTLM and Kerberos details
• Timeouts and Errors^[14] — timeout semantics and the exception surface