Parse CLI Help Output

2.0.0 · active · verified Wed Apr 22

parse-help is a JavaScript utility for programmatically parsing the help output of command-line interfaces, extracting structured information about their flags, options, and aliases. It provides a structured object representation of CLI options, making it easier to analyze or process them within other tools. The current stable version is 2.0.0. The package is maintained by Sindre Sorhus, known for a high volume of small, focused utility packages, typically implying a stable but not necessarily rapid release cadence unless new features or breaking changes warrant it. A key differentiator is its focus specifically on parsing *help output* rather than building a CLI from scratch or parsing `argv` directly, making it useful for introspection or documentation generation from existing CLIs.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to `require()` parse-help in a CommonJS context when parse-help is a pure ESM package.

fix Change your import statement from `const parseHelp = require('parse-help');` to `import parseHelp from 'parse-help';` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
```
SyntaxError: Cannot use import statement outside a module
```
cause Using `import parseHelp from 'parse-help';` in a file that Node.js is treating as CommonJS.

fix Ensure the file where you are using the import statement is treated as an ES module. This typically means adding `"type": "module"` to your `package.json` or changing the file extension to `.mjs`.

Warnings

breaking parse-help v2.0.0 is a pure ESM module. It no longer supports CommonJS `require()` and must be used with `import` statements in an ESM environment.
Fix: Ensure your project is configured for ESM. If using Node.js, add `"type": "module"` to your `package.json` or use `.mjs` file extensions. Update `require('parse-help')` to `import parseHelp from 'parse-help';`.
breaking Node.js 12 or newer is now required for parse-help v2.0.0. Older Node.js versions are not supported.
Fix: Upgrade your Node.js environment to version 12 or higher. To maintain compatibility with older Node.js versions, you must stick to parse-help v1.x.
gotcha The package specifically parses 'help output' as a string. It does not execute a CLI or interact with `process.argv` directly. The quality and format of the output heavily depend on the consistency and standard adherence of the input help string.
Fix: Provide well-formatted help text that resembles common CLI help output. Test `parseHelp` with various actual outputs from your target CLIs to ensure correct parsing.

Install

npm install parse-help npm
yarn add parse-help yarn
pnpm add parse-help pnpm

Imports

parseHelp
wrong:
```
const parseHelp = require('parse-help');
```
correct:
```
import parseHelp from 'parse-help';
```
Since v2.0.0, parse-help is a pure ESM module and must be imported using ES modules syntax. CommonJS `require()` is no longer supported.

Quickstart

Demonstrates how to import and use `parseHelp` to process a sample CLI help string and output the structured flags and aliases.

import parseHelp from 'parse-help';

const helpOutput = `
	Usage
	  $ my-cli <command> [options]

	Options
	  -v, --verbose    Enable verbose logging
	  --config <path>  Specify a configuration file (default: config.json)
	  -h, --help       Show help information

	Examples
	  $ my-cli start
	  $ my-cli build --config custom.json
`;

const parsed = parseHelp(helpOutput);

console.log('Parsed Flags:', JSON.stringify(parsed.flags, null, 2));
console.log('Parsed Aliases:', JSON.stringify(parsed.aliases, null, 2));

/*
Output would be:
Parsed Flags: {
  "verbose": {
    "alias": "v",
    "description": "Enable verbose logging"
  },
  "config": {
    "description": "Specify a configuration file (default: config.json)"
  },
  "help": {
    "alias": "h",
    "description": "Show help information"
  }
}
Parsed Aliases: {
  "v": "verbose",
  "h": "help"
}
*/

view raw JSON →