Review the documentation before the 2.3.00 release

README.md

@@ -7,13 +7,14 @@
 
 See **[Project Documentation](https://metricshub.org/winrm-java)** and the [Javadoc](https://metricshub.org/winrm-java/apidocs) for more information on how to use this library in your code.
 
-The Windows Remote Management (WinRM) Java Client is a library that enables to:
-* Connect to a remote Windows server using one of three authentication types (NTLM, Kerberos, or Basic)
-* Execute WMI Query Language (WQL) queries which uses HTTP/HTTPS protocols.
+The Windows Remote Management (WinRM) Java Client is a library that lets you:
+* Connect to a remote Windows server over HTTP or HTTPS with NTLM, Kerberos, or Basic authentication
+* Run WMI Query Language (WQL) queries and remote commands (`cmd.exe` or PowerShell)
+* Upload, read, list, and download remote files
 
 > ## ⚠️ Upgrading from 1.x
 >
-> Version 2.0.0 **removed the legacy Apache CXF backend**: the dependency-free **light** client is
+> Version 2.0.00 **removed the legacy Apache CXF backend**: the dependency-free **light** client is
 > the only implementation (same documented entry points; a few CXF/SMB-only public types were
 > removed). The main consequence:
 >
@@ -101,18 +102,10 @@ try (WinRMClient client = WinRMClient.builder("server01.acme.com")
 }
 ```
 
-Connection-scoped options on the builder: `https()`, `port(int)`,
-`authentication(AuthScheme.KERBEROS, AuthScheme.NTLM)` (ordered fallback; NTLM is the default —
-Kerberos in the list requires `https()`),
-`ticketCache(Path)`, `namespace(String)`, `trustAllCertificates()` (per-client alternative to the
-`org.metricshub.winrm.tls.insecure` system property; insecure, testing only), and
-`sslContext(SSLContext)` for a dedicated trust store.
-
-Per-operation options: `namespace(...)`, `timeout(...)`, and for WQL enumeration tuning
-`pageSize(int)` (WS-Enumeration `MaxElements`, 32000 by default) and `pullTimeout(Duration)`
-(`MaxTime` per Pull). Commands accept `workingDirectory(String)`, `charset(Charset)` (see
-[Character encoding](#character-encoding)), and `upload(Path...)` to copy local script files and
-rewrite the command to reference the remote copies.
+Every builder and request option (transport, authentication, TLS, timeouts, retries, working
+directory, environment, stdin, uploads, ...) is described on the
+[project site](https://metricshub.org/winrm-java) and in the
+[Javadoc](https://metricshub.org/winrm-java/apidocs).
 
 ### Character encoding
 
@@ -218,7 +211,7 @@ cleanup, and command-line substitution — are documented on the
 upgrade warning above); `trustAllCertificates()` on the builder or
 `-Dorg.metricshub.winrm.tls.insecure=true` trusts all certificates (insecure, testing only).
 Kerberos uses the ambient Kerberos configuration (`krb5.conf` / `-Djava.security.krb5.*`) unless
-the command-line KDC and realm options described below are used.
+the CLI's `--kerberos-kdc` / `--kerberos-realm` options are used.
 
 ### Legacy API
 
@@ -289,7 +282,7 @@ server, so no Windows host is needed in CI.
 ### Live run against a real host
 
 `WinRMLiveTest` runs a WQL query and a command against a **real** WinRM host (the successor of
-the pre-2.0.0 CXF-vs-light differential harness). It is skipped unless `winrm.live.host` is set:
+the pre-2.0.00 CXF-vs-light differential harness). It is skipped unless `winrm.live.host` is set:
 
 ```bash
 mvn test -Dtest=WinRMLiveTest \
@@ -305,16 +298,13 @@ for hosts with self-signed certificates).
 
 ## Release instructions
 
-The artifact is deployed to Sonatype's [Maven Central](https://central.sonatype.com/).
-
-The actual repository URL is https://s01.oss.sonatype.org/, with server Id `ossrh` and requires credentials to deploy
-artifacts manually.
-
-But it is strongly recommended to only use [GitHub Actions "Release to Maven Central"](actions/workflows/release.yml) to perform a release:
+The artifact is deployed to [Maven Central](https://central.sonatype.com/) through the Central
+Portal (server id `central`, inherited from `oss-parent`). Release only with the
+["Release to Maven Central"](https://github.com/metricshub/winrm-java/actions/workflows/release.yml)
+GitHub Actions workflow:
 
-* Manually trigger the "Release" workflow
+* Manually trigger the "Release to Maven Central" workflow
 * Specify the version being released and the next version number (SNAPSHOT)
-* Release the corresponding staging repository on [Sonatype's Nexus server](https://s01.oss.sonatype.org/)
 * Merge the PR that has been created to prepare the next version
 
 ## License

src/main/java/org/metricshub/winrm/CommandRequest.java

@@ -264,12 +264,12 @@ public CommandRequest charset(final Charset charset) {
 	 * output charset. Default: the output charset (see {@link #charset(Charset)}).
 	 * <p>
 	 * The two directions are not symmetric on Windows. Output follows the shell's console code
-	 * page, which this client pins to UTF-8. Input written to a command created with
-	 * <i>console-mode</i> stdin is converted by the WinRM service with the remote machine's
-	 * <b>ANSI</b> code page instead — so an interactive session (the CLI's {@code shell}
-	 * subcommand) must encode what it sends with that code page, whatever the console code page
-	 * is. Input handed to a command created with pipe semantics (any {@code stdin(...)} on this
-	 * request) reaches the process unconverted and needs no override.
+	 * page (UTF-8 unless {@link WinRMClient.Builder#consoleCodePage(int)} says otherwise). Input
+	 * handed to a command created with pipe semantics (any {@code stdin(...)} on this request)
+	 * reaches the process unconverted and needs no override. Input written to a command created
+	 * with <i>console-mode</i> stdin is converted by the WinRM service with a code page that
+	 * depends on the Windows version: prefer pipe semantics, or set this to match the console
+	 * code page.
 	 *
 	 * @param charset the input charset
 	 * @return this request

src/main/java/org/metricshub/winrm/WindowsRemoteCommandResult.java

@@ -20,6 +20,10 @@
  * ╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱
  */
 
+/**
+ * The result of a command run by the legacy WinRMCommandExecutor: its output, exit code and
+ * execution time.
+ */
 public class WindowsRemoteCommandResult {
 
 	private final String stdout;
@@ -32,7 +36,7 @@ public class WindowsRemoteCommandResult {
 	 *
 	 * @param stdout The stdout of the command
 	 * @param stderr The stderr of the command
-	 * @param executionTime The execution time of the command in milliseconds
+	 * @param executionTime The execution time of the command in seconds
 	 * @param statusCode The command return status code
 	 */
 	public WindowsRemoteCommandResult(
@@ -50,7 +54,7 @@ public WindowsRemoteCommandResult(
 	/**
 	 * Get the stdout of the command.
 	 *
-	 * @return
+	 * @return the standard output of the command
 	 */
 	public String getStdout() {
 		return stdout;
@@ -59,7 +63,7 @@ public String getStdout() {
 	/**
 	 * Get the stderr of the command.
 	 *
-	 * @return
+	 * @return the standard error of the command
 	 */
 	public String getStderr() {
 		return stderr;
@@ -68,7 +72,7 @@ public String getStderr() {
 	/**
 	 * Get the execution time of the command in seconds.
 	 *
-	 * @return
+	 * @return the execution time, in seconds
 	 */
 	public float getExecutionTime() {
 		return executionTime;
@@ -77,7 +81,7 @@ public float getExecutionTime() {
 	/**
 	 * Get the return status code of the command
 	 *
-	 * @return
+	 * @return the exit code of the command
 	 */
 	public int getStatusCode() {
 		return statusCode;

src/main/java/org/metricshub/winrm/WqlResult.java

@@ -57,7 +57,7 @@ public final class WqlResult implements Iterable<WqlRow> {
 
 	/**
 	 * Get the column names, in the order they appear in the WQL query ({@code SELECT *} yields
-	 * the order the server returned).
+	 * them in case-insensitive alphabetical order).
 	 *
 	 * @return an unmodifiable list of column names
 	 */

src/main/java/org/metricshub/winrm/cli/WinRmCli.java

@@ -728,17 +728,17 @@ private static String help() {
 			"  winrm-java [options] cat <file> [cat options]\n" +
 			"  winrm-java [options] get <file> [<local path>]\n" +
 			"\n" +
-			"Connection options:\n" +
+			"Options (before the subcommand):\n" +
 			"  -h, --hostname <host>       Target hostname or IP address (required)\n" +
-			"  -u, --username <user>       User name, optionally DOMAIN\\\\user (required)\n" +
+			"  -u, --username <user>       User name, optionally DOMAIN\\user (required)\n" +
 			"  -p, --password <password>   Password (visible to local processes; avoid in automation)\n" +
 			"  -pf, --password-file <file> Read a UTF-8 password from a file (preferred for automation)\n" +
 			"  -P, --port <port>           Target port (default: HTTP 5985, HTTPS 5986)\n" +
 			"  -t, --timeout <ms>          Operation timeout in milliseconds (default: 60000)\n" +
 			"  -d, --directory <path>      Working directory of the remote command or shell\n" +
 			"      --env <NAME=VALUE>      Environment variable of the remote command or shell (repeatable)\n" +
 			"      --profile               Load the user profile in the remote command or shell\n" +
-			"  -i, --stdin                 Forward the local standard input to the remote command\n" +
+			"  -i, --stdin                 Always forward the local standard input (automatic when redirected)\n" +
 			"      --https                 Use HTTPS\n" +
 			"      --https-permissive      Trust any HTTPS certificate and hostname (insecure)\n" +
 			"      --ntlm                  Use NTLM authentication (default)\n" +

src/main/java/org/metricshub/winrm/command/WinRMCommandExecutor.java

@@ -49,18 +49,18 @@ private WinRMCommandExecutor() {}
 	 * path on the remote system where the files have been copied.
 	 * Example:
 	 * <code>
-	 * 		WinRemoteCommandExecutor.execute(
-	 * 		"CSCRIPT c:\\MyScript.vbs", null, "remote-srv", null, null, null, 30000, Arrays.asList("c:\\MyScript.vbs"), false);
+	 * 		WinRMCommandExecutor.execute(
+	 * 		"CSCRIPT c:\\MyScript.vbs", null, "remote-srv", null, "DOMAIN\\user", password, null, 30000, List.of("c:\\MyScript.vbs"), null, null);
 	 * </code>
-	 * This will copy <b>c:\\MyScript.vbs</b> to <b>remote-srv</b>, typically in
-	 * <b>C:\\Windows\\Temp\\winrm-upload-MYHOST</b> and the command that is executed will therefore
-	 * become:
-	 * <code>CSCRIPT "C:\\Windows\\Temp\\winrm-upload-MYHOST\\MyScript.vbs"</code>
+	 * This will copy <b>c:\MyScript.vbs</b> to <b>remote-srv</b>, typically in
+	 * <b>C:\Windows\Temp\winrm-upload-MYHOST</b> under a content-addressed name, and the command
+	 * that is executed will therefore become:
+	 * <code>CMD.EXE /C (CSCRIPT C:\Windows\Temp\winrm-upload-MYHOST\MyScript.1a2b3c4d5e6f.vbs)</code>
 	 *
 	 * @param command The command to execute. (Mandatory)
 	 * @param protocol The HTTP protocol (HTTP by default)
 	 * @param hostname Host to connect to. (Mandatory)
-	 * @param port The port (5985 for HTPP or 5986 for HTTPS by default)
+	 * @param port The port (5985 for HTTP or 5986 for HTTPS by default)
 	 * @param username The username name. (Mandatory)
 	 * @param password The password.
 	 * @param workingDirectory Path of the directory for the spawned process on the remote system (can be null)