[Bug]: <command> --help prints the top-level help instead of that command's help #4708

Primary area

Cua Driver

Summary

cua-driver <command> --help ignores the command and prints the same text as cua-driver --help. For recording, sessions and config, that text names the command only in its Subcommands: list and gives none of the command's subcommands, arguments or options. As a result, cua-driver recording --help does not tell the user about recording start <output-dir> or recording render <input-dir> <out-mp4>.

Reproduction

Run on either build listed under Environment. None of these commands needs a running daemon.

cua-driver --help > top.txt
cua-driver recording --help > rec.txt; echo "exit=$?"
cmp top.txt rec.txt && echo identical
grep -c 'cua-driver recording ' rec.txt
for c in sessions config history extension channel; do cua-driver "$c" --help | cmp -s - top.txt && echo "$c: identical"; done

Expected behavior

The CLI reference (docs/content/docs/cua-driver/reference/cli/index.mdx) says "Run cua-driver <command> --help for the build you have." Under "Global options" it says "--help prints help for any command". cua-driver recording --help should therefore print help for recording: its subcommands start <output-dir>, stop, status and render <input-dir> <out-mp4>, plus render's --scale and --no-zoom flags, as docs/content/docs/cua-driver/reference/cli/recording.mdx documents them.

Actual behavior

On both builds, cua-driver recording --help exited 0, and cmp printed identical: the output matched cua-driver --help byte for byte. That output begins with Usage: cua-driver [SUBCOMMAND] [OPTIONS] and the Subcommands: list, and no line contains cua-driver recording (grep -c printed 0). Elsewhere, "Recording" appears only in the permissions text about the Screen Recording permission. On both builds the loop printed identical for sessions, config, history, extension and channel. The top-level text has no cua-driver sessions or cua-driver config usage line either, although it does include usage blocks for some commands, such as extension and channel.

Environment

• Cua Driver 0.33.4, the installed release build.
• Cua Driver 0.34.0, the cua-driver-rs-0.34.0-darwin-arm64.tar.gz release archive (tag cua-driver-rs-v0.34.0, commit b0968e1b12834e485dda68789541a3cc57664a9f). At the time of testing, main differed from that tag only in installer scripts and a release-state file.
• macOS 27.0.1, arm64.

Evidence

• Expected source: docs/content/docs/cua-driver/reference/cli/index.mdx (introduction and "Global options") and the usage in docs/content/docs/cua-driver/reference/cli/recording.mdx, both marked Version: 0.34.0. The two quoted sentences come from the docs generator template (scripts/docs-generators/lib/cli-mdx.ts:623 and :642), so they promise this for every command. The recording usage comes from cua-driver dump-docs --type cli.
• Failure source: the command output described under Actual behavior. In libs/cua-driver/rust/crates/cua-driver/src/cli.rs:540 on main, parse_command checks for --help or -h anywhere in argv before it reads the command, then prints one fixed help text.
• Evidence provenance: observed
• Local verification: reproduced
• Reproduction completeness: complete

Workaround and additional context

Workaround: On both builds, cua-driver dump-docs --type cli exited 0 and printed each command's arguments and options. On 0.34.0, the output was checked to include recording render's input-dir and out-mp4. The online CLI reference gives the same usage. Both are read-only.

Restoration check: Failing now: cua-driver recording --help prints the top-level help, byte-identical to cua-driver --help, with no recording usage. Restored: cua-driver recording --help exits 0 and prints help for recording that names start <output-dir>, stop, status, and render <input-dir> <out-mp4>. render's --scale and --no-zoom flags appear either there or in cua-driver recording render --help. sessions --help and config --help likewise describe their own commands. Control: cua-driver --help and cua-driver --version still print their current output and exit 0. A --help flag still stops the command from running; for example, cua-driver recording start <dir> --help must not start a recording.

Submission checks

• I searched for duplicate issues and active pull requests.
• This issue describes a single problem.
• I removed credentials, private data, sensitive screenshots, and vulnerability details from this public report.