Shell environment variables: environment(name, value) on the fluent API and --env NAME=VALUE on the CLI (winrs -env)

[bertysentry]

winrs parity: -env[ironment]:STRING=VALUE — set environment variables for the remote shell.

Context

The WSMan shell protocol supports setting environment variables at shell creation: the rsp:Shell body of the Create request carries

<rsp:Environment>
  <rsp:Variable Name="FOO">bar</rsp:Variable>
  <rsp:Variable Name="BAZ">qux</rsp:Variable>
</rsp:Environment>

The client has no support for this today. Like WorkingDirectory, it is a shell-scoped setting: the remote shell is created by the client's first command and reused afterward.

Proposed API

CommandResult result = client.command("build.cmd")
    .environment("BUILD_NUMBER", "42")
    .environment("CONFIG", "release")
    .execute();

Same contract as workingDirectory(String), documented the same way: honored when the shell is created, i.e. by the client's first command (and every streaming/blocking terminal shares it).

CLI

--env NAME=VALUE, repeatable (winrs-style multiple occurrences), valid for command and the future shell subcommand (#136):

winrm-java -h server -u 'DOMAIN\user' -pf pw.txt \
  --env BUILD_NUMBER=42 --env CONFIG=release \
  exec build.cmd

Requirements

• New optional rsp:Environment block in Envelopes.createShell — mind the rsp:Shell child element order (MS-WSMV Shell_Type is a schema sequence: Environment comes before WorkingDirectory, before the stream declarations); verify against a real Windows host, WinRM is picky about this.
• Pinning semantics like the working directory (see the reaped-shell fix in Add the fluent WinRMClient API: builders, typed results, unchecked exceptions #133/PR): the environment is pinned by the first command and must be replayed with its ORIGINAL values when the shell is silently recreated after the server reaped it — a recreation must stay invisible.
• Values XML-escaped; names validated non-blank; insertion order preserved (LinkedHashMap).
• CLI parsing: --env repeatable, NAME=VALUE split on the first =, usage error otherwise; document in the CLI manual.
• Tests: wire assertion of the Environment block on Create (FakeWsmanServer), pinned replay on shell recreation, CLI parsing, docs (commands.md + cli.md).

🤖 Generated with Claude Code