Configurable user-profile loading: loadUserProfile() and --profile (#139)

[bertysentry]

Closes #139.

What

Load the user profile in the remote command shell, the opposite of winrs -noprofile. The default is unchanged: without the option, the client still sends WINRS_NOPROFILE=TRUE.

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

CLI: --profile, valid with command and shell, like -d and --env.

Design: a client setting, not a per-command one

The issue proposed client.command(...).loadUserProfile(), pinned by the client's first command like workingDirectory(...). This PR makes it a builder setting instead (decided while implementing), next to consoleCodePage(...), whose WINRS_CODEPAGE travels in the same Create OptionSet:

• For a long-lived client like MetricsHub's, "the first command pins it" would make the setting depend on whichever command happens to run first.
• Every shell the client creates gets it for free: commands, the upload(...) transfer legs, the PowerShell file fallback, remote file operations, and the silent recreation of a reaped shell. The per-command form needed two new WindowsRemoteExecutor SPI overloads and threading through every ShellFileCopy leg; Codex caught exactly that gap for environment on Shell environment variables: environment(name, value) on the fluent API and --env NAME=VALUE on the CLI (winrs -env) #156.
• The 10-argument LightWinRMService.createInstance overload added by Kerberos credential delegation: allowDelegation() and CLI --allow-delegate (winrs -allowdelegate) #141 is not released yet, so it takes the new parameter in place rather than gaining yet another overload.

Verified live

On Windows Server 2008 R2, with a local account that has no session on the host:

	Without the profile (default)	With --profile
%USERPROFILE%, starting directory	C:\Users\Default	C:\Users\<user>
%APPDATA%, %LOCALAPPDATA%	not set	the user's own
%TEMP%	C:\Windows\Temp	the user's own
HKEY_CURRENT_USER	not the user's hive (a marker written with the profile is invisible)	the user's hive

The CLI shell subcommand shows the same difference in its prompt: C:\Users\Default> without the option, C:\Users\<user>> with it.

On the Server 2016, 2019 and 2022 test hosts both modes behave the same, because those accounts' profiles were already loaded: interactive or disconnected sessions, and on the 2016 host a hive that the User Profile Service log shows loaded since 2026-09-04. The docs state this: without the option, a command sees the profile only if something else already loaded it.

Not verified: the failure for an account that is not a local administrator, because every test account is an administrator. The docs cite Microsoft's winrs documentation for it; the failure surfaces as a WinRMFaultException, the path every Create fault takes.

Tests

• WinRMClientTest.expiredCachedShellIsRecreatedAndTheCommandRetried: with loadUserProfile(), both Create requests carry WINRS_NOPROFILE=FALSE, the original shell's and the one recreated after the reap.
• WinRmCliTest: the full-stack exec and shell tests pass --profile and assert it on the wire (the shell session opens its own connection). The help test covers the new line.
• CliArgumentsTest: off by default; --profile is rejected outside command and shell.
• WsmanProtocolTest already asserted the default TRUE.
• mvn clean verify site is green on JDK 25: 319 tests, and checkstyle, PMD and SpotBugs report nothing. CI runs it on JDK 17.

Docs

• Remote Commands: a new Loading the user profile section.
• CLI manual: the --profile row, and a fix to the -d default, which is C:\Users\Default when the profile is not loaded.
• Migrating from winrm4j: winrm4j hardcodes WINRS_NOPROFILE=FALSE, so migrated commands lose the profile unless the client calls loadUserProfile().

Found along the way

#183: piping input into a command that exits without reading it fails the run with fault 232 and loses the output. It is a pre-existing race, unrelated to this change.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-27T22:58:44.216823Z	5ada4cf	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5ada4cf891

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".