Remote file access (4/4): CLI ls, stat, cat and get subcommands

[bertysentry]

Fourth and last issue of the remote file access family: expose the library features from the CLI. Depends on the three library issues: #145 (listing), #146 (reading), #147 (download).

Context

The CLI already covers the library's other capabilities (wql, command/exec/cmd/run, shell). Once the library can list and read remote files, the CLI is where that becomes genuinely useful day to day: inspecting a remote log or configuration file from a shell script, with no RDP session and no SMB share.

Proposed subcommands

# List: long format, machine-readable timestamps and sizes
winrm-java -h server -u 'DOMAIN\user' -pf pw.txt ls 'C:\inetpub\logs' --glob '*.log' --recursive --depth 3

# One path's properties
winrm-java ... stat 'C:\Windows\Temp\collect.log'

# Content to stdout
winrm-java ... cat 'C:\Windows\Temp\collect.log'
winrm-java ... cat 'D:\logs\huge.log' --offset -8192            # tail the last 8 KiB
winrm-java ... cat 'D:\logs\huge.log' --offset 1073741824 --length 65536
winrm-java ... cat 'C:\legacy\report.txt' --charset windows-1252

# Whole file to a local file, digest-verified
winrm-java ... get 'C:\Windows\Temp\collect.log' ./collect.log

Requirements

• ls — default output is a fixed, parseable long format (attributes, size, ISO-8601 UTC timestamp, path), not a locale-formatted human table. Options: --glob, --recursive, --depth N, --files-only, --directories-only, --modified-after <ISO-8601>, --min-size, and --json for JSON Lines output consistent with what wql already emits. Entries are written as the listing streams, like the WQL rows — no buffering of the whole tree.
• stat — the same fields for a single path, one field per line (and --json). Exit code distinguishes "does not exist" from a genuine failure, per the existing exit-code contract.
• cat — writes raw bytes to stdout by default, so binary content and redirection to a file both work (... cat 'C:\x.bin' > x.bin must produce a byte-exact file: no charset round-trip, no newline translation). --charset switches to decoded text; --offset/--length map to the ranged read, negative offset = from the end.
• get — the downloadFile terminal, with the destination defaulting to the remote file's base name in the current directory when omitted. Progress reporting goes to stderr only (never stdout, which may be the content or a pipe), and only when stderr is a terminal.
• Inaccessible entries reported on stderr, exit code reflects partial failure: a recursive ls over a tree with access-denied subdirectories must not exit 0 while silently having skipped part of the tree.
• Path arguments are passed through untouched to the library, which does the quoting. Document the shell-quoting the user needs locally ('C:\path with spaces\x.log', and the trailing-backslash trap in double-quoted POSIX shells).
• Diagnostics on stderr, content on stdout — the existing invariant, and the one thing that makes cat/get scriptable.
• Exit codes reuse the established CLI contract; add a documented code for "remote path not found" if the current set has no good fit.

Tests & docs

• CliArguments parsing tests for every new subcommand and option, including the usage errors (bad --depth, malformed --modified-after, --length without --offset, unknown charset).
• End-to-end CLI tests against FakeWsmanServer: ls streaming output ordering, --json shape, cat byte-exactness on stdout (including a byte sequence that would be corrupted by any text round-trip), stat on a missing path → documented exit code.
• cli.md is the single source of truth for the CLI manual: document the four subcommands, their options, output formats, exit codes and quoting notes there; --help stays short and links to https://metricshub.org/winrm-java/cli.html. README gets one example line, no more.

Acceptance criteria

• The four subcommands work end to end against a real host.
• winrm-java ... cat <binary file> > out.bin produces a byte-exact copy.
• A recursive ls over a partially inaccessible tree reports the skipped paths on stderr and exits non-zero.
• --help stays short; cli.md documents everything.
• mvn verify site green: no checkstyle/PMD/SpotBugs findings, full Javadoc, cli.md updated.

🤖 Generated with Claude Code