Remote Commands

Running a command

Build a WinRMClient^[1], then prepare the command with command(...) and run it with execute():

import java.time.Duration;
import org.metricshub.winrm.CommandResult;
import org.metricshub.winrm.WinRMClient;

try (WinRMClient client = WinRMClient.builder("server.example.com")
        .https()
        .credentials("DOMAIN\\Administrator", password)
        .timeout(Duration.ofSeconds(30))
        .build()) {

    CommandResult result = client.command("ipconfig /all").execute();

    System.out.println("exit code: " + result.exitCode());
    System.out.print(result.stdout());
    System.err.print(result.stderr());
}

The command line is run through cmd.exe by the remote shell. One client can run any number of commands (and WQL queries^[2]) over the same authenticated connection — see the Overview^[3] for the builder options.

The result

CommandResult^[4] is an immutable value:

Streaming the output

execute() collects the complete output in memory and returns only when the command has exited. For long-running or verbose commands, end the same request with start() instead: it returns a RemoteProcess^[5] — shaped like java.lang.Process — whose output can be consumed while the command is still running:

try (RemoteProcess process = client.command("wevtutil qe System /f:text").start()) {
    try (BufferedReader out = process.stdout()) {
        out.lines().forEach(this::process);
    }
    int exitCode = process.waitFor();       // or waitFor(Duration) for an overall deadline
}

Points to know:

• Close the process — use try-with-resources. Closing before completion sends the WinRM terminate Signal, which actually stops the remote command; a command drained to its end cleans up on its own. Closing the readers does not close the process.
• stdout() and stderr() are fed by the same protocol loop: reading either channel (or calling waitFor()) advances it, and output arriving for the channel not being read is buffered until read — memory is bounded by the unread channel, not by the total output.
• Output is decoded incrementally with the request's charset; a multibyte character split across protocol chunks is decoded correctly.
• The process holds the client's serial connection until completion or close: other operations on the same client wait in the meantime.
• The timeout is an inactivity timeout — the longest silence tolerated from the server — not an overall deadline: a command may run (and stream) far longer than the timeout as long as it keeps producing output. Use waitFor(Duration) when you need a hard deadline. See Timeouts and Errors^[6].

Standard input

Commands that read their standard input can be fed in two ways.

CommandResult result = client.command("sort")
    .stdin(Path.of("data.txt"))     // also stdin(InputStream) and stdin(String)
    .execute();

try (RemoteProcess p = client.command("some-repl.exe").stdin().start()) {
    try (BufferedWriter in = p.stdin()) {
        in.write("first request\n");
        in.flush();                              // delivers the buffered text
        System.out.println(p.stdout().readLine());
    }                                            // close() = end of input (EOF)
    p.waitFor();
}

CommandResult result = client.command("longRunningThing.exe")
    .onStdout(chunk -> log.info(chunk))
    .onStderr(chunk -> log.warn(chunk))
    .execute();

Character encoding

The output character set never needs to be specified. The remote command shell is created with console code page 65001, so its output is UTF-8 whatever the remote machine's locale, and it is decoded as such — no detection query, no per-host configuration:

// On a French Windows host:
client.command("vol").execute().stdout();   // " Le numéro de série du volume est …"

A handful of legacy console tools — net.exe and chcp.com are the known ones — ignore the console code page and write their text pre-converted to the machine's OEM code page. Their accented characters are not valid UTF-8 and arrive as U+FFFD; decode those commands with the matching OEM charset instead:

client.command("net user Administrateur")
    .charset(Charset.forName("IBM850"))     // French/Western European OEM code page
    .execute();

charset(...) is also what you want for a command that repoints the console itself (a leading chcp) or writes raw bytes in a known encoding to its standard output. WQL results are unaffected by all of this: they travel as UTF-8 inside the SOAP envelope.

Changed in 2.0.00 — earlier versions ran a SELECT CodeSet FROM Win32_OperatingSystem query before the first command and decoded the output with the code page it reported. That property is the remote machine's ANSI code page, which never matched what the shell emitted, so non-ASCII command output was mangled on every non-English host.

Copying local files to the host

Pass one or more local files to upload(...) to have them copied to the remote host before the command runs. Every reference to an uploaded file in the command line is rewritten to the path where the file lands on the host:

CommandResult result = client.command("CSCRIPT c:\\scripts\\collect.vbs")
    .upload(Path.of("c:\\scripts\\collect.vbs"))
    .execute();

copies c:\scripts\collect.vbs to the host and runs the equivalent of:

CSCRIPT "C:\Windows\Temp\...\collect.1a2b3c4d5e6f.vbs"

The client can also copy a file to an explicit destination of your choice, independently of any command:

client.uploadFile(Path.of("collect.ps1"), "C:\\Windows\\Temp\\collect.ps1");

In short: files travel through the WinRM command shell itself (chunked base64, decoded with certutil, digest-verified — no SMB, no TCP port 445, no administrative share), land under a content-addressed name (e.g. collect.1a2b3c4d5e6f.vbs), and a file already present with an identical digest is not transferred again. The mechanism is designed for small script files, not bulk data.

See File Transfers^[7] for the full mechanics: the exact destination directory, the temporary files, the integrity verification, the 30-day cleanup, and the command-line substitution rules.

Exceptions

execute() reports failures through the unchecked WinRMClientException^[8] hierarchy:

See Timeouts and Errors^[6] for details.

From the command line

The standalone jar runs a command with its command subcommand, forwarding the output live and propagating the exit code — see the Command-Line Client^[12] manual.