Overview

The WinRM Java Client is a small library that talks to the Windows Remote Management (WS-Management) service on a remote Windows host. It lets a Java application:

• run WQL / WMI queries such as SELECT Name, State FROM Win32_Service and read the rows back (WQL Queries^[1]), and
• execute remote commands, capturing standard output, standard error and the exit code — optionally copying local script files to the host first (Remote Commands^[2]).

Both operations can also stream: WQL rows are consumed page by page as they arrive (stream()), and command output is consumed while the command is still running (start(), returning a java.lang.Process-like handle) — memory stays bounded regardless of the result size.

It supports NTLM over HTTP (with message encryption) and HTTPS, and Kerberos (SPNEGO) over HTTPS (Authentication^[3]).

Since 2.0.0 the client has zero runtime dependencies (no Apache CXF / JAX-WS / JAXB stack, no SMB stack) and is immune by construction to JAXP ServiceLoader conflicts, because it uses the JDK-default XML factories. Problems are reported through exceptions only — the library pulls in no logging framework.

Add the dependency

The library is published on Maven Central^[5].

<dependency>
  <groupId>org.metricshub</groupId>
  <artifactId>winrm-java</artifactId>
  <version>2.0.00</version>
</dependency>

implementation 'org.metricshub:winrm-java:2.0.00'

implementation("org.metricshub:winrm-java:2.0.00")

See Installation^[6] for the coordinates, the supported JDKs, and the standalone command-line jar.

A first WQL query

Everything starts with the fluent WinRMClient^[8] builder — one client authenticates once and can run any number of queries and commands over the same connection:

import java.time.Duration;
import org.metricshub.winrm.WinRMClient;
import org.metricshub.winrm.WqlResult;
import org.metricshub.winrm.WqlRow;

public class Example {

    public static void main(String[] args) {
        try (WinRMClient client = WinRMClient.builder("server.example.com")
                .credentials("DOMAIN\\Administrator", "the-password".toCharArray())
                .timeout(Duration.ofSeconds(30))
                .build()) {

            WqlResult result = client.wql("SELECT Name, State FROM Win32_Service").execute();

            System.out.println(result.columns());       // [Name, State]
            for (WqlRow row : result) {
                System.out.println(row.string("Name") + " is " + row.string("State"));
            }
        }
    }
}

Remote commands work the same way:

CommandResult result = client.command("ipconfig /all").execute();
System.out.println(result.stdout());

Failures are reported through the unchecked WinRMClientException^[9] hierarchy. The static one-shot helpers that predate WinRMClient (WinRMWqlExecutor.executeWql(...)^[10], WinRMCommandExecutor.execute(...)^[11]) remain available and unchanged, with their checked exceptions.

Where to go next

• Installation^[6] — coordinates, supported JDKs, and the standalone CLI jar
• Preparing the Windows Host^[7] — prerequisites on the target: enabling WinRM and the privileges the account needs
• WQL Queries^[1] — query WMI and read the result
• Remote Commands^[2] — run commands and copy files to the host
• File Transfers^[12] — how files are copied through the WinRM channel
• Command-Line Client^[13] — the standalone jar's manual page
• Authentication^[3] — NTLM and Kerberos
• TLS / HTTPS^[14] — certificate validation and trust stores
• Timeouts and Errors^[15] — timeout semantics and the exception surface
• Migrating from 1.x^[4] — the 2.0.0 breaking changes, and moving to the fluent API
• Legacy API^[16] — the static one-shot helpers that predate WinRMClient