Long command descriptions

[Lakitna]

I'm in a situation where I need less technical people to use my code. A CLI works great for me here, but I think it would be good to add a bunch of documentation to it.

Which leads me to what looks to be a limitation of the current commander. I want the help text to do something like this:

Expected

> my-app --help
Usage: my-app <command> [options]

Options:
  -V, --version           output the version number
  -h, --help              display help for command

Commands:
  execute [options]       Execute a very interesting command.
  help [command]          display help for command

> my-app execute --help
Usage: my-app execute [options]

Execute a very interesting command. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Curabitur tristique interdum ullamcorper. Mauris malesuada viverra mattis. Donec aliquet, ligula nec
placerat mollis, purus est rutrum leo, a dapibus mi tortor quis turpis. Cras non commodo tortor.
Etiam laoreet dui risus. Curabitur lacus purus, euismod vitae odio quis, tincidunt posuere elit.
Mauris gravida tempus mi, sit amet condimentum lectus eleifend vel. Nam posuere quam vel lorem
mattis, ut tristique eros pretium. Curabitur eget lobortis libero. Integer leo urna, luctus nec
turpis et, consequat imperdiet elit. Nunc eu quam id lectus vulputate ultricies non eu dolor.
Aliquam luctus vulputate feugiat. Proin consectetur at lorem at congue. Ut dolor quam, dapibus et
arcu eu, porttitor pharetra turpis.

Options:
  -V, --version           output the version number
  -h, --help              display help for command

Commands:
  help [command]          display help for command

Current

When I simply add all the text to .description() it will also render the full text in > my-app --help. This makes it very hard to read.

> my-app --help
Usage: my-app <command> [options]

Options:
  -V, --version           output the version number
  -h, --help              display help for command

Commands:
  execute [options]       Execute a very interesting command. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Curabitur tristique interdum ullamcorper. Mauris malesuada viverra mattis. Donec aliquet, ligula nec
placerat mollis, purus est rutrum leo, a dapibus mi tortor quis turpis. Cras non commodo tortor.
Etiam laoreet dui risus. Curabitur lacus purus, euismod vitae odio quis, tincidunt posuere elit.
Mauris gravida tempus mi, sit amet condimentum lectus eleifend vel. Nam posuere quam vel lorem
mattis, ut tristique eros pretium. Curabitur eget lobortis libero. Integer leo urna, luctus nec
turpis et, consequat imperdiet elit. Nunc eu quam id lectus vulputate ultricies non eu dolor.
Aliquam luctus vulputate feugiat. Proin consectetur at lorem at congue. Ut dolor quam, dapibus et
arcu eu, porttitor pharetra turpis.
  help [command]          display help for command

> my-app execute --help
Usage: my-app execute [options]

Execute a very interesting command. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Curabitur tristique interdum ullamcorper. Mauris malesuada viverra mattis. Donec aliquet, ligula nec
placerat mollis, purus est rutrum leo, a dapibus mi tortor quis turpis. Cras non commodo tortor.
Etiam laoreet dui risus. Curabitur lacus purus, euismod vitae odio quis, tincidunt posuere elit.
Mauris gravida tempus mi, sit amet condimentum lectus eleifend vel. Nam posuere quam vel lorem
mattis, ut tristique eros pretium. Curabitur eget lobortis libero. Integer leo urna, luctus nec
turpis et, consequat imperdiet elit. Nunc eu quam id lectus vulputate ultricies non eu dolor.
Aliquam luctus vulputate feugiat. Proin consectetur at lorem at congue. Ut dolor quam, dapibus et
arcu eu, porttitor pharetra turpis.

Options:
  -V, --version           output the version number
  -h, --help              display help for command

Commands:
  help [command]          display help for command

Potential solutions

Overwrite help

In #1225 you mention splitting up the help command in header, body, and footer. Using that I can overwrite --help and insert more text into it. Though I believe overwriting help like this might lead to some stuff not working properly anymore?

Summary method

Another solution is to introduce another method. For example:

program
  .command('execute')
  .description('A very long text, only displayed when there is actually room to display everything. This is shown only in the help body.')
  .summary('The short description shown in the command section');

Limit description

The final solution I can think of is to remove all line-breaks and limit the number of characters when showing the description in the commands section. You can also try and make this a bit nicer by only showing everything before the first . or something like that.

program
  .command('execute')
  .description(`A very long text. I'm actually too long to fully show in the commands section as thing will become very messy.\nI even contain line breaks!\n\nThat's not what the description method was designed for!`);

results in:

> my-app --help
Usage: my-app <command> [options]

Options:
  -V, --version           output the version number
  -h, --help              display help for command

Commands:
  execute [options]       A very long text. I'm actually too long to fully show in the commands section as the thing ...
  help [command]          display help for command

> my-app execute --help
Usage: my-app execute [options]

A very long text. I'm actually too long to fully show in the commands section as the thing will become very messy.
I even contain line breaks!

That's not what the description method was designed for!

Options:
  -V, --version           output the version number
  -h, --help              display help for command

Commands:
  help [command]          display help for command

[shadowspawn]

Nice description of your problem and some potential solutions, thanks.

There is support for added text after the built-in help using an event listener. This is the best solution currently available. https://github.com/tj/commander.js#custom-help

[shadowspawn]

I am working on a big refactor of the help formatting in #1365. It includes a hook for the subcommand description, so would allow (say) only displaying the first line of the description:

program.configureHelp({
   commandDescription: (cmd) => {
      return cmd.description.split('\n', 1)[0];
   });
});

[shadowspawn]

Enhanced support for customised help has shipped in Commander 7.0.0, although not separate command summary and description as suggested here.

This issue has not had any activity in over six months. It isn't likely to get acted on due to this report.

Feel free to open a new issue if it comes up again, with new information and renewed interest.

Thank you for your contributions.

[shadowspawn]

Opened a PR to add .summary() for a short summary to use when listing subcommands.