Document that the Windows launcher alters values with cmd.exe metacharacters (#219)

src/site/markdown/cli.md

@@ -182,6 +182,18 @@ character of a `-p` or `-u` value that this code page lacks (Cyrillic or CJK on
 European system, for instance) reaches the CLI as `?`, and the BMC refuses the login. Put such a
 password in a UTF-8 file and pass it with `-pf`.
 
+The Windows launcher is a batch file, so `cmd.exe` parses the command line before the CLI sees
+it, from PowerShell as well. A `%NAME%` reference is replaced by the variable wherever it is;
+outside double quotes, `^` is dropped, `&` and `|` end the arguments and run what follows as a
+command (`-p 'a&ver'` logs in with `a`, then runs `ver`), and `<` and `>` end them and redirect
+the input or output of the CLI to the file that follows (`-p 'a>out.txt'` logs in with `a` and
+writes the output to `out.txt`). PowerShell puts double quotes only around a value that contains
+a space, so a `-p`, `-u`, `--name` or `-pf` value with one of these characters and no space
+(`C:\R&D\pw.txt`) does not reach the CLI as typed; from `cmd.exe`, a value in double quotes is
+safe except for `%NAME%`. Give such a password at the prompt or in a file with `-pf`, and such a
+path or name through `java -jar` from PowerShell, where Java receives every value unchanged
+(from `cmd.exe`, `java -jar` goes through the same parsing as the launcher).
+
 Secrets are never printed: not in the usage errors, not with `--verbose`, not in the failure
 messages. The CLI wipes its copies of the password and of the key when it ends, but a `-p` or
 `-k` value stays in memory as text that the CLI cannot wipe (the JVM keeps its command line in the

src/site/markdown/installation.md

@@ -81,7 +81,10 @@ installer runs in Windows PowerShell 5.1 and PowerShell 7. Neither installer nee
 The launcher finds a Java runtime, 8 or later, each time it runs: `IPMICLI_JAVA_HOME`, then
 `JAVA_HOME`, then `java` on the `PATH` (on Linux and macOS, then `/usr/libexec/java_home`, sdkman
 and `/usr/lib/jvm`). Installing or upgrading Java needs no reinstallation. Without a suitable
-runtime, it exits with code 127 and points to [Adoptium](https://adoptium.net).
+runtime, it exits with code 127 and points to [Adoptium](https://adoptium.net). The Windows
+launcher is a batch file: a `%NAME%` reference, and `^`, `&`, `|`, `<` or `>` outside double
+quotes, do not reach `ipmicli` as typed (see
+[Passwords and BMC key](cli.html#passwords-and-bmc-key)).
 
 ```shell-session
 $ ipmicli --version

src/site/resources/get.ps1

@@ -146,6 +146,9 @@ $shim | Set-Content -Path $shimPath -Encoding ASCII
 
 Write-Host "Installed the IPMI Java Client jar to $jarPath"
 Write-Host "Installed the ipmicli launcher to $shimPath"
+Write-Host 'The launcher is a batch file: a %NAME% reference, and ^ & | < > outside double quotes'
+Write-Host '(PowerShell quotes only a value with a space), do not reach ipmicli as typed.'
+Write-Host 'Give such a password at the prompt or in a file (-pf).'
 
 # --- PATH registration -----------------------------------------------------------