Add support to print help/usage of util.parseArgs

[alexkiro]

What is the problem this feature will solve?

An almost ubiquitous practice of writing a CLI is including a help command in the CLI itself. Currently anyone using util.parseArgs needs to write their own help command. This, in my opinion, makes parseArgs incomplete.

What is the feature you are proposing to solve the problem?

My suggestion is to include the ability to prin help/usage information generated directly from the config given to parseArgs. A minimum would be something along the lines of:

1. Include help text for each ParseArgsOptionConfig to include help text for each option in particula:

foo: {    
 type: 'boolean',    
 short: 'f',   
 help: 'enable foo',
},

2. Add a main help text to the ParseArgsConfig as well, to include details on what the CLI as a whole:

parseArgs({ 
  help: 'Use this command to achieve foo',
  options: {
    // ...
  }
});

3. Add the --help/-h option to print the generated usage information either:

• always add the --help/-h option, and automatically print the usage and exit the process when parsing the args (E.g. how python's builtin argparse does it); this would be a breaking change since it may conflict with other similar options implemented already.
• add a new option to the ParseArgsConfig to enable autogenerated help option if desired

parseArgs({ 
  enableHelp: true,
  help: 'Use this command to achieve foo',
  options: {
    // ...
  }
});

• simply provide a method to print the usage and let the user implement it themselves in userland

const { values, positionals, printUsage } = parseArgs({
  help: 'Use this command to achieve foo',
  options: {
    help: {
      type: "boolean",
      short: "h",
      help: "print command line options and exit"
    }
  }
});
if (values.help) {
  printUsage();
  process.exit(0);
}

What alternatives have you considered?

No response

[ljharb]

This would be great; I’ve been using a wrapper around parseArgs for this.

[bakkot]

If we're going to do this, my inclination would be to do both the enableHelp thing (to automatically add --help and have that print-and-exit) and the printUsage thing. Although I'd just always return a usage when there's any help options specified, instead of returning a printUsage function (so that you can print it some other way, e.g. as part of a larger message about invalid arguments, or with a footer or something. It's not like it's expensive to compute the string up front).

There is a lot of possible design space here; if this goes in, we should be explicit that it is only intended to support the most basic of uses. For example, I don't think we should be trying to automatically derive the name of the command or the version number from package.json, even though that's convenient.

The one additional thing I'd add would be the ability to specify the argument placeholder for string-based options, as in --threads <NUM> or whatever - there's not really a way to infer a reasonable name to use for the placeholder and you do need to include one. (Well, you don't strictly need to, but I think you should.)

Some prior art:

• https://github.com/voxpelli/peowly
• https://github.com/bcomnes/argsclopts
• https://github.com/75lb/command-line-usage (not for parseArgs specifically)
• others, probably?

[shadowspawn]

For interest I searched for people rolling their own help to see what people are doing. Lots of additions in the displayed help with (variously) usage, color, examples, program descriptions, aligned option descriptions, aligned long options, wrapped option descriptions, and option defaults. In the files I looked at the displayed help is hand-crafted and independent of the configuration passed to parseArgs.

https://github.com/search?q=%2Fimport.*parseArgs.*util%2F+%22help%3A%22+%28language%3Ajavascript+OR+language%3Atypescript%29+NOT+is%3Afork+&type=code

[miguelmarcondesf]

Hello there!
I have a PR #58875
Please, I would appreciate a few more sets of eyes there to see if I'm headed in the right direction.
Thank you in advance!

[mb21]

For what it's worth, I quickly hacked this together as follows (see https://github.com/mastrojs/mastro/blob/main/src/generator.ts#L95):

  import { parseArgs, type ParseArgsOptionDescriptor } from "node:util";

  const options: { [opt: string]: ParseArgsOptionDescriptor & { description: string }; } = {
    help: {
      description: "Print this help page",
      type: "boolean",
      short: "h",
    },
    "output": {
      description: "Name of output folder that will be created",
      type: "string",
    }
  };
  const { values } = parseArgs({ options });

  if (values.help) {
    const keys = Object.keys(options);
    const maxKeyLen = Math.max(...keys.map(k => k.length));
    const opts = keys.map(key => ` --${key.padEnd(maxKeyLen)}  ${options[key].description}`);
    console.info("Options:\n" + opts.join("\n"));
  }