POC supporting verbose descriptions for commands

[brandenrodgers]

Description and Context

I was poking around Stripe's CLI and noticed they support multiple descriptions for commands. A short one that shows when the command is listed a a child of another command, and a longer one when you run the help command for a specific command. Our equivalent would be hs --help vs. hs auth --help. For the former, it's nice to provide a concise description because the list of commands is long and it's hard to parse if each command has a wordy description. For the latter, it would be ideal to give the user more detailed information.

Unfortunately, yargs doesn't make this easy out of the box, but I think I found a pretty clean solution that would let us provide both a short and long description for commands. This POC shows what it could look like for the hs auth command.

The addVerboseDescribe is pretty straightforward. It checks to see if the user included the --help flag, grabs the original help output, and then logs out a new one. I tried to make it safer by allowing it to safely throw. If it throws, the help output will just fall back to the default yargs behavior, which is to log out the command's describe export.

Screenshots

hs --help before

hs --help after

hs auth --help before

hs auth --help after

(ignore the "undefined" in there. I just didn't pass in the config file constant to i18n)

TODO

Who to Notify

[brandenrodgers]

Updated screenshots for hs auth --help

Before

After

[brandenrodgers]

Even if commands don't specify verbose descriptions, they can still benefit from the formatting updates:

Before

After