feat(cli): consistent flags, deduplicated commands and accurate help #92

Context

Audit of the CLI on 2026-11-09: user-visible inconsistencies and duplicates. All verified on main at 949d449.

• -o is the output format on check/status/doctor/fleet, a directory on backup (backup.go:182, default /raid/backup, DGX-specific) and a file on user backup (user.go:137).
• tenant passwd and tenant reset are the same command from one constructor (tenant.go:28,331).
• tunnel install says "Install cloudflared binary" but runs the whole cloudflared module Apply (tunnel.go:31), overlapping tunnel setup and apply --module cloudflared.
• user add --pubkey duplicates the persistent --ssh-pubkey; user passwd --suffix is described as a legacy scheme that builds predictable passwords (users.go:1048-1060).
• Stale help: status hint shows gpu assign <user> <indices> (real: --gpus 0,1, status.go:323); user rehome [USERNAME] requires the name; root Short omits Rocky and fleet; --profile help hardcodes the list; no command has Example.
• Gaps: no schedule status; fleet targets registers --host/--group/--all and ignores them; fleet schedule cannot pass --on-calendar; fleet --dry-run still demands --yes.

Implementation starts only on the owner's go-ahead.

Decisions

• Renamed or removed flags keep a cobra deprecated alias for at least one minor release; the release notes list them under Action needed.
• -o/--output means output format everywhere.

• 2026-11-09: user passwd --suffix is deprecated now and removed in the next minor release; tunnel install becomes an alias of tunnel setup. Basis: owner decision in the planning session.

• 2026-11-09: replace the former DGX VLAN address in CLI help and prompts (root --vlan-address flag help, the interactive VLAN prompt in apply) with a TEST-NET example (203.0.113.10/32). Basis: review of PR fix(profiles)!: keep site-specific and no-op values out of the embedded profiles #101.

Design

• backup --dir (default derived from the state/home base), user backup --file; -o/--output kept as deprecated aliases on both.
• tenant reset → alias of tenant passwd.
• user add --pubkey deprecated in favour of --ssh-pubkey; user passwd --suffix deprecated.
• Help text fixes; Example on apply, check, user add, gpu assign, tenant create, fleet apply; --profile help from config.AvailableProfiles().
• schedule status; fleet targets honours selection; fleet schedule enable --on-calendar; fleet --dry-run without --yes.

Changes

• internal/cli/{backup,user,userlife,tenant,tunnel,status,root,schedule,fleet}.go, tests, README/command reference, release notes.

Acceptance criteria

• AC1: rootfiles backup -o X still works and prints a deprecation notice naming --dir.
• AC2: rootfiles tenant --help lists one password command; reset still resolves.
• AC3: a test walks the cobra tree and fails when any Use contains a flag or an [ARG] marked optional while Args requires it.
• AC4: rootfiles schedule status shows the timer state; fleet targets --host h limits output.
• AC5: release notes list every deprecated flag with its replacement.

Tasks

• T1: output-flag rename with aliases (AC1)
• T2: tenant/user/tunnel duplicates and deprecations (AC2)
• T3: help text, examples, cobra-tree lint test (AC3)
• T4: schedule status, fleet gaps (AC4)
• T5: release notes (AC5)

Out of scope

• Merging check/status/doctor: they differ by design (drift exit 2 / overview exit 0 / live health) and fleet sudoers depend on all three. Their help text will say so.