fix(cli): describe every cmux cloud verb in its help

Merged
TE
7d ago
+692-126

Leo, 2026-10-30: "How about more cmux-platform audits, improvements, features, fixes, optimizations, polish, plus the ui that gets people (or agents) using it". Also 2026-10-29: "let's just get the cloud and its respective ui up to snuff".

An agent with no GUI starts with cmux cloud --help. Until now that printed 54 verb names in two columns, with no descriptions or examples, rows that didn't line up (firewall-delete domain-list), and no sign that kill-machine needs --confirm. cmux cloud kill-machine --help printed the same list again.

With this change:

  • cmux cloud --help opens with a quick start (list, new, exec, pause, resume and kill a machine). It lists every verb by group (machines, run and connect, files, snapshots, ports, network, chats, account), one line each in a single column, and marks the four verbs that need --confirm. It says these actions need the app signed in (cmux cloud sign-in) and points to cmux vm --help when there is no app.
  • cmux cloud <verb> --help prints only that verb: its usage line with flags, what it does, and cmux action describe cloud <verb> --json for the full argument list.
  • cmux help cloud now follows the locale. Before, it always printed the English text.
  • English and Japanese for all of it (the Rust CLI's two locales).

The verbs now live in one table, cli/cloud_help.rs, which also moves about 100 lines out of cli.rs. A test fails when the table and the catalog's offered cloud ā€¦ verbs differ in either direction. Other tests check that every description starts in the same column, that both languages are filled in, that the --confirm verbs are marked, and that each quick-start command parses. The cloud exec parse error now uses the table's usage line, so the two can't drift apart.

Before (cmux cloud --help, excerpt):

CLI actions (the live action catalog is authoritative):
  firewall-get              firewall-create
  firewall-delete            domain-list
  publication-list           list-machines
  new-terminal-on-machine    rename-machine
  kill-machine               pause-machine

After (excerpt; the full output is from the binary built at this head):

QUICK START
  cmux cloud list-machines --json
  cmux cloud new-machine --size small --json
  cmux cloud exec --target machine:MACHINE_ID --command 'uname -a' --json
  cmux cloud pause-machine --target machine:MACHINE_ID
  cmux cloud resume-machine --target machine:MACHINE_ID
  cmux cloud kill-machine --target machine:MACHINE_ID --confirm

MACHINES
  list-machines                List machines with their ids and targets
  new-machine                  Create a machine; answers its machine_id
  ...
  kill-machine                 Delete a machine and everything on it (--confirm)

$ cmux cloud kill-machine --help
usage: cmux cloud kill-machine --target machine:MACHINE_ID --confirm

Delete a machine and everything on it.

Every argument: `cmux action describe cloud kill-machine --json` (with the app running)

Validation: cargo test -p cmux-tui --lib -- cli::cloud_help cli::tests cli::extra_help localization passed (169 tests) on the Linux fast-checks runner, along with cargo clippy -p cmux-tui --all-targets -D warnings and cargo fmt --check. check-no-godfiles.sh --only rust --base origin/feat-cmux-next passes. The help output above came from running cmux-tui built at this commit in English and LANG=ja_JP.UTF-8.

Localization audit: the changed surface is CLI help text in cmux-tui. Each new string has English and Japanese in the same table, and a test fails when one is missing or copied. No Swift or web strings change.

Takes back #27108: its four added rows (open-desktop, apply-machine-config, deliver-secrets, start-session) move into the cli/cloud_help.rs table with the rest of the old CLOUD_HELP list; nothing it added is dropped, and the catalog test still requires all four.

Risk: low. Help text and one parse-error string; no behavior change for any verb. The per-verb usage lines are written by hand from CloudActionDescriptions.swift and the catalog. The test catches a verb that is added or removed, but not a renamed flag, which is why each verb's help points to cmux action describe. #25651 adds rows to the old CLOUD_HELP const. If this lands first, those rows move into the table in cli/cloud_help.rs, and the catalog test names any it misses.

Agent session: agent session

šŸ¤– Generated with Claude Code