{"id":11029,"library":"help-me","title":"help-me command line help utility","description":"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.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/mcollina/help-me","tags":["javascript","help","command","minimist","commist"],"install":[{"cmd":"npm install help-me","lang":"bash","label":"npm"},{"cmd":"yarn add help-me","lang":"bash","label":"yarn"},{"cmd":"pnpm add help-me","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Partner for parsing command-line arguments, commonly used with help-me.","package":"minimist","optional":true},{"reason":"Partner for dispatching commands, often used to integrate help-me into a command system.","package":"commist","optional":true},{"reason":"Utility for resolving file paths in ESM contexts, frequently used to determine the `dir` option for help-me.","package":"desm","optional":true}],"imports":[{"note":"CommonJS default export. The function returned by `require()` is the main entry point for CJS modules.","wrong":"const { helpMe } = require('help-me')","symbol":"helpMe","correct":"const helpMe = require('help-me')"},{"note":"ESM named export. Used in modern Node.js environments with `import` statements and supports top-level await.","wrong":"import help from 'help-me'","symbol":"help","correct":"import { help } from 'help-me'"}],"quickstart":{"code":"import { help } from 'help-me'\nimport { join } from 'desm'\nimport { fileURLToPath } from 'url'\nimport { dirname } from 'path'\nimport { mkdirSync, existsSync, writeFileSync } from 'fs'\n\n// Setup for __dirname equivalent in ESM\nconst __filename = fileURLToPath(import.meta.url)\nconst __dirname = dirname(__filename)\nconst docDir = join(__dirname, 'doc')\n\n// Ensure the 'doc' directory exists\nif (!existsSync(docDir)) {\n  mkdirSync(docDir, { recursive: true })\n}\n\n// Create a dummy help file for the example\nconst helpFilePath = join(docDir, 'hello.txt')\nif (!existsSync(helpFilePath)) {\n  writeFileSync(helpFilePath, 'This is a detailed help message for the \"hello\" command.\\n\\nUsage: mycli hello <name>')\n}\n\n// Instantiate and use the help function\n// help-me expects a path to a directory containing help files.\n// The help function is then called with options and the command arguments.\nconsole.log('--- Displaying help for \"hello\" command ---\\n')\nawait help({\n  dir: docDir,\n  ext: '.txt',\n  // Optional: customize \"no such help\" message\n  noHelp: (command) => `No help available for command: ${command.join(' ')}`\n}, ['hello'])\n\n// Example of requesting help for a non-existent command\nconsole.log('\\n--- Displaying help for \"unknown\" command ---\\n')\nawait help({\n  dir: docDir,\n  ext: '.txt',\n  noHelp: (command) => `No help available for command: ${command.join(' ')}`\n}, ['unknown'])\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"ENOENT: no such file or directory, stat '/path/to/doc/command.txt'"},{"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.","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'`).","error":"TypeError: help is not a function"}],"ecosystem":"npm"}