Revise/reformat usage message to improve readability in typical terminal window widths

[tomwheeler]

Is your feature request related to a problem? Please describe.

The CLI supports 10 commands, most of which offer several subcommands and support various command-line flags. Although I use the CLI every day, I do not (and likely never will) have all of these memorized, so I often type temporal [command] help to view the usage message.

I find the output difficult to read because it's wide enough that "description" column to wraps around to a second line (and sometimes even a third line) where it can no longer be distinguished from text in the "flag" column. The example below shows what the output looks like in a standard 80-character terminal window:

$ temporal
Temporal command-line interface and development server.

Usage:
  temporal [command]

Available Commands:
  activity    Complete or fail an Activity.
  batch       Manage Batch Jobs
  completion  Generate the autocompletion script for the specified shell
  env         Manage environments.
  help        Help about any command
  operator    Manage a Temporal deployment.
  schedule    Perform operations on Schedules.
  server      Run Temporal Server.
  task-queue  Manage Task Queues.
  workflow    Start, list, and operate on Workflows.

Flags:
      --color string                                      Set coloring. Accepted 
values: always, never, auto. (default "auto")
      --env string                                        Environment to read en
vironment-specific flags from. (default "default")
      --env-file $HOME/.config/temporalio/temporal.yaml   File to read all envir
onments (defaults to $HOME/.config/temporalio/temporal.yaml).
  -h, --help                                              help for temporal
      --log-format string                                 Log format. Options ar
e "text" and "json". Default is "text".
      --log-level server start-dev                        Log level. Default is 
"info" for most commands and "warn" for server start-dev. Accepted values: debug
, info, warn, error, never. (default "info")
      --no-json-shorthand-payloads                        Always show all payloa
ds as raw payloads even if they are JSON.
  -o, --output string                                     Data output format. No
te, this does not affect logging. Accepted values: text, json, jsonl, none. (def
ault "text")
      --time-format string                                Time format. Accepted 
values: relative, iso, raw. (default "relative")
  -v, --version                                           version for temporal

For reference, this was also a problem with tctl, whose longest line was 152 characters. However, the output is significantly wider in the new CLI; version 0.12.0's usage message has at least one line of output exceeding 200 characters. At my preferred font size, I can't widen my terminal wide enough to eliminate this line wrapping on my 32-inch external monitor, let alone my much smaller 16-inch built-in display.

Describe the solution you'd like

I see two ways of addressing this, which could be used independently or together.

The first is to make the message to be more concise. By eliminating duplicate information (such as the --env-file flag's two mentions of the default file path) and leaving some details (such as listing the default value and all accepted values) to the documentation, this could likely get the width down to 140 characters or so.

The second is to format the output so that line wrapping happens within the appropriate column, as some other programs do (qemu-io, for example). The output from the above command might look like this if formatted for 100 characters:

$ temporal
Temporal command-line interface and development server.

Usage:
  temporal [command]

Available Commands:
  activity    Complete or fail an Activity.
  batch       Manage Batch Jobs
  completion  Generate the autocompletion script for the specified shell
  env         Manage environments.
  help        Help about any command
  operator    Manage a Temporal deployment.
  schedule    Perform operations on Schedules.
  server      Run Temporal Server.
  task-queue  Manage Task Queues.
  workflow    Start, list, and operate on Workflows.

Flags:
      --color string                                      Set coloring. Accepted values: always,
                                                          never, auto. (default "auto")
      --env string                                        Environment to read environment-specific
                                                          flags from. (default "default")
      --env-file $HOME/.config/temporalio/temporal.yaml   File to read all environments (default:
                                                          $HOME/.config/temporalio/temporal.yaml).
  -h, --help                                              help for temporal
      --log-format string                                 Log format. Options are "text" and
                                                          "json". Default is "text".
      --log-level server start-dev                        Log level. Default is "info" for most
                                                          commands and "warn" for server start-dev.
                                                          Accepted values: debug, info, warn,
                                                          error, never. (default "info")
      --no-json-shorthand-payloads                        Always show all payloads as raw payloads
                                                          even if they are JSON.
  -o, --output string                                     Data output format. Note, this does not
                                                          affect logging. Accepted values: text,
                                                          json, jsonl, none. (default "text")
      --time-format string                                Time format. Accepted values: relative,
                                                          iso, raw. (default "relative")
  -v, --version                                           version for temporal

Run java -help for example of a different variation on formatting long lines in a usage message, which is perhaps an even better fit than what's shown above.

Additional context

N/A

[cretz]

Will leave this open, but we might not get control over this FYI (or wrestling control may be more of a struggle than it's worth). But will let whoever picks this up decide.

[josh-berry]

This will be partially addressed by #561 once it lands, because we'll be reformatting the source material to the default 80-column width. More work will be needed after that though (e.g. for options).