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 Client options^[3].

try (WinRMClient client = WinRMClient.builder("server.example.com")
        .credentials("DOMAIN\\user", password)
        .loadUserProfile()
        .build()) {
    client.command("reg query HKCU\\Software\\Vendor").execute();
}

Running PowerShell

powerShell(...) prepares a PowerShell script execution the same way command(...) prepares a command line. The script travels base64-encoded (powershell.exe -NoProfile -NonInteractive -EncodedCommand …; -NoProfile skips PowerShell's profile scripts, not the Windows user profile of loadUserProfile()), so no quoting or escaping is ever needed: quotes, pipes, newlines, and $variables reach PowerShell exactly as written.

CommandResult result = client.powerShell(
        "Get-Service | Where-Object { $_.Status -eq 'Running' } | Select-Object -First 5 Name"
    ).execute();

It returns the same request object as command(...): every option and terminal described on this page — timeout(...), charset(...), stdin(...), onStdout(...), execute(), start() — works unchanged.

Points to know:

• Exit code — powershell.exe exits with 0 on success and 1 when the script ends with a terminating error; call exit <n> in the script for a specific code.
• Standard error — powershell.exe may write progress records to stderr as CLIXML (#< CLIXML followed by <Objs …>), even when the script succeeds: judge success by the exit code, not by an empty stderr().
• Uploads — upload(...) works as with any command: references to the uploaded files in the script are rewritten to the remote copies before the script is encoded.
• Script size — none to worry about. A script too long for the encoded command line (roughly 3000 characters and up; the remote shell's limit is 8191) is transferred automatically as a temporary .ps1 file, like upload(...), and content-addressed^[8], so an identical re-run skips the transfer. Its content runs as a dot-sourced script block, so it behaves like the encoded form: no script path ($PSScriptRoot and $MyInvocation.MyCommand.Path stay empty), top-level param(...) works, and the execution policy does not apply; only $MyInvocation.InvocationName and Line differ. As with any upload, the transfer creates the remote shell, so workingDirectory(...) does not apply.
• Windows PowerShell — the script runs in powershell.exe, whose version depends on the host (5.1 on current Windows, down to 2.0 on Windows Server 2008 R2 and Windows 7): write for the oldest one you target. To target PowerShell 7+, invoke pwsh yourself with command(...).

The result

CommandResult^[9] is an immutable value:

A nonzero exit code is not an exception: check exitCode().

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^[10] — 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(System.out::println);
    }
    int exitCode = process.waitFor();       // blocks until the command exits
}

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, so use a second client for any call made while consuming the process.
• 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. For a hard deadline, use waitFor(Duration): it returns true once the command has completed (read the code with exitCode()), or false when the deadline passes first, with the command still running (close() stops it). See Timeouts and Errors^[11].

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

Standard input

Commands that read their standard input can be fed in two ways. Either way, input the command does not read (it exits without reading it, or before the input arrives) is discarded without error, and the command's output and exit code are reported as usual.

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();
}

Character encoding

The output character set never needs to be specified, unless the client is built with consoleCodePage(...) (see Input encoding). 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.

Byte order mark. PowerShell 2.0 (Windows Server 2008 R2, Windows 7) writes a UTF-8 byte order mark ahead of its redirected output. When the output is decoded as UTF-8, a U+FEFF at the very start of stdout and of stderr is dropped by every terminal, callback and reader (and by the legacy WinRMCommandExecutor). A U+FEFF anywhere else is kept as data: PowerShell 2.0 emits it mid-stream when a direct [Console]::Out or [Console]::Error write comes first. With any other charset(...), the bytes are decoded as they are. File reads (client.file(...)) return the file's content untouched, byte order mark included.

Changed in 2.0.00 — earlier versions ran a SELECT CodeSet FROM Win32_OperatingSystem query before each 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\winrm-upload-MYHOST\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^[8] 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(), start() and the RemoteProcess methods report failures through the unchecked WinRMClientException^[12] hierarchy:

See Timeouts and Errors^[11] 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^[15] manual.