help-me command line help utility

5.0.0 · active · verified Sun Apr 19

help-me is a lightweight Node.js utility designed to simplify the creation and display of help messages for command-line interfaces. It serves as a direct partner for argument parsers like `minimist` and command dispatchers such as `commist`, allowing developers to define structured help documentation in simple text files. Currently at version 5.0.0, the package sees an active development and maintenance cadence, with recent updates focusing on modernizing its codebase and reducing dependencies, notably dropping `glob` in v5.0.0. Its primary differentiator lies in its straightforward, file-based approach to help documentation and its minimal API surface, making it an ideal choice for projects already leveraging `minimist` or `commist` that require a simple, declarative help system without the overhead of larger CLI frameworks.

Common errors

```
ENOENT: no such file or directory, stat '/path/to/doc/command.txt'
```
cause The help command was invoked for a command (e.g., 'command') for which a corresponding help file ('command.txt') does not exist in the configured documentation directory.

fix Verify that the `dir` option points to the correct directory containing your help files and that the requested command's help file exists (e.g., `command.txt` for `['command']`). Ensure file names match command arguments.
```
TypeError: help is not a function
```
cause This error typically occurs when attempting to use `help-me` with incorrect import syntax, such as using CommonJS `require()` with named destructuring (`const { help } = require('help-me')`) or importing the ESM `help` function as a default import (`import help from 'help-me'`).

fix For CommonJS, use `const helpMe = require('help-me')` to get the default export function. For ESM, use `import { help } from 'help-me'` for the named export.

Warnings

breaking Version 5.0.0 removed the 'glob' dependency. This change may affect how help files are resolved or impact functionality relying on wildcard path matching for help documentation that was previously available.
Fix: Review help file path resolution and ensure no reliance on glob-like patterns. Update paths to be explicit or use alternative file discovery mechanisms if glob-like functionality is required.
breaking Version 4.0.0 introduced significant internal modernization, dependency reductions, and a move towards 'exact match' for help file lookup. This may alter previous fuzzy matching behavior for command help files.
Fix: Thoroughly test help file resolution and command matching logic after upgrading to v4.0.0 to ensure correct behavior, especially if previous versions relied on non-exact matching or implicit path resolution.
gotcha When using `help-me` in an ESM module, resolving the `dir` option (where help files are located) requires using `import.meta.url` in conjunction with a utility like `desm` or Node.js's `fileURLToPath` and `path.dirname` to correctly derive file system paths. Directly using `__dirname` is not available in ESM.
Fix: Ensure your `dir` option is an absolute file system path when using ESM. Use `import { join } from 'desm'` with `join(import.meta.url, 'your-doc-folder')` or manually construct the path with `fileURLToPath` and `dirname`.

Install

npm install help-me npm
yarn add help-me yarn
pnpm add help-me pnpm

Imports

helpMe
wrong:
```
const { helpMe } = require('help-me')
```
correct:
```
const helpMe = require('help-me')
```
CommonJS default export. The function returned by `require()` is the main entry point for CJS modules.
help
wrong:
```
import help from 'help-me'
```
correct:
```
import { help } from 'help-me'
```
ESM named export. Used in modern Node.js environments with `import` statements and supports top-level await.

Quickstart

This quickstart demonstrates how to initialize `help-me` in an ESM module, dynamically create a documentation directory and a sample help file, and then display help messages for both existing and non-existent commands using top-level await.

import { help } from 'help-me'
import { join } from 'desm'
import { fileURLToPath } from 'url'
import { dirname } from 'path'
import { mkdirSync, existsSync, writeFileSync } from 'fs'

// Setup for __dirname equivalent in ESM
const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
const docDir = join(__dirname, 'doc')

// Ensure the 'doc' directory exists
if (!existsSync(docDir)) {
  mkdirSync(docDir, { recursive: true })
}

// Create a dummy help file for the example
const helpFilePath = join(docDir, 'hello.txt')
if (!existsSync(helpFilePath)) {
  writeFileSync(helpFilePath, 'This is a detailed help message for the "hello" command.\n\nUsage: mycli hello <name>')
}

// Instantiate and use the help function
// help-me expects a path to a directory containing help files.
// The help function is then called with options and the command arguments.
console.log('--- Displaying help for "hello" command ---\n')
await help({
  dir: docDir,
  ext: '.txt',
  // Optional: customize "no such help" message
  noHelp: (command) => `No help available for command: ${command.join(' ')}`
}, ['hello'])

// Example of requesting help for a non-existent command
console.log('\n--- Displaying help for "unknown" command ---\n')
await help({
  dir: docDir,
  ext: '.txt',
  noHelp: (command) => `No help available for command: ${command.join(' ')}`
}, ['unknown'])

view raw JSON →