Registry / devops / simple-bin-help

simple-bin-help

library1.8.0jsnpmunverified

simple-bin-help is a utility library for Node.js CLI (Command Line Interface) scripts, providing essential features like automatic help message display, argument validation, and update notifications. Currently stable at version 1.8.0, its release cadence is moderate, with updates typically focusing on dependency bumps and minor improvements rather than rapid feature additions. Key differentiators include its consolidated approach to common CLI boilerplate, offering a single function call to handle `--help` / `--version` flags, enforce minimum argument counts (`minArguments`), and integrate `update-notifier` for prompting users about new versions. It allows for customizable help strings, an `onFail` callback for custom error handling, and a `noExit` option to control the default `process.exit()` behavior, providing flexibility for different CLI design patterns.

devops

npm install simple-bin-help

github ↗package ↗

INSTALL

IMPORT

SIG · SIMPLE-BIN-HELP

simple-bin-help

devopsjavascriptv1.8.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

simpleBinHelp (direct invocation)

✓ require('simple-bin-help')({ minArguments: 3, help: '...' });

✗ import simpleBinHelp from 'simple-bin-help'; simpleBinHelp({ ... });

Primarily designed for CommonJS `require()` in Node.js CLI scripts. While usable in ESM via `import` with proper Node.js setup (e.g., `type: module` in package.json or wrapper), direct `require` is the canonical usage demonstrated in documentation.

simpleBinHelp (assigned function)

✓ const simpleBinHelp = require('simple-bin-help'); simpleBinHelp({ minArguments: 3, help: '...' });

✗ import { simpleBinHelp } from 'simple-bin-help';

The module exports a single function as its default. There are no named exports from the top-level module.

simpleBinHelp (ESM dynamic import)

✓ const { default: simpleBinHelp } = await import('simple-bin-help'); simpleBinHelp({ minArguments: 3, help: '...' });

✗ import simpleBinHelp from 'simple-bin-help';

For ESM projects consuming this CommonJS module, dynamic import is a robust way to access the main function, which is available on the `.default` property of the imported module object.

Demonstrates basic argument validation and automatic help/version display for a Node.js CLI script, using `minArguments` and a `package.json` path. It also highlights the default `process.exit()` behavior.

#!/usr/bin/env node // filename: my-cli-tool.js const path = require('path'); const simpleBinHelp = require('simple-bin-help'); // Configure help and argument validation simpleBinHelp({ minArguments: 3, // Requires 'node', 'my-cli-tool.js', and one more argument packagePath: path.join(__dirname, '..', 'package.json'), // Path to your project's package.json help: 'Usage: my-cli-tool <required-argument>\n\nThis tool processes a single string argument.', // By default, simple-bin-help calls process.exit() if validation fails or help/version is shown. // Set noExit: true if you want to handle the exit logic yourself. noExit: false }); // If the script reaches this point, arguments were valid and help/version was not displayed. console.log(`Hello from my-cli-tool!`); console.log(`Received argument: ${process.argv[2]}`); console.log('Continuing with main CLI logic...'); // Example usage: // 1. Create a dummy ../package.json: {"name": "my-cli-tool", "version": "1.0.0"} // 2. Run: `node my-cli-tool.js "some value"` (Valid) // 3. Run: `node my-cli-tool.js` (Shows help and exits) // 4. Run: `node my-cli-tool.js -h` (Shows help and exits) // 5. Run: `node my-cli-tool.js -v` (Shows version and exits)

Debug

Known issues

gotchaBy default, `simple-bin-help` invokes `process.exit()` if argument validation fails or if `--help` (`-h`) or `--version` (`-v`) flags are present. This can abruptly terminate your CLI script's execution if not accounted for.

fix

To prevent automatic exiting, set the `noExit: true` option in the configuration object. When `noExit` is true, the function returns a boolean indicating success/failure, allowing you to manage exit logic yourself.

affects: >=1.0.0

gotchaThe `minArguments` option counts `process.argv` elements, which always include the `node` executable path and the script file path itself. Therefore, to require *one* actual command-line argument from the user, you must set `minArguments: 3` (e.g., `node script.js arg1`).

fix

Adjust `minArguments` by adding 2 to the number of *actual* required user arguments (e.g., for 1 user arg, set `minArguments: 1 + 2 = 3`).

affects: >=1.0.0

gotchaThe `packagePath` option must point to a valid `package.json` file for `simple-bin-help` to correctly display the package version (`-v`, `--version`) and use the `update-notifier` feature. Incorrect paths will lead to missing version information or `update-notifier` failures.

fix

Ensure `packagePath` is an absolute path or a correct relative path using `path.join(__dirname, '..', 'package.json')` for a typical bin script setup where the script is in `bin/` and `package.json` is in the project root.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'simple-bin-help'

The 'simple-bin-help' package is not installed or not resolvable from the script's execution context.

fix

Run `npm install simple-bin-help` in your project directory. Ensure the package is listed in your `dependencies` in `package.json` and that `npm install` has been executed.

The CLI script unexpectedly exits immediately without executing its main logic (e.g., 'process exited with code 1').

`simple-bin-help` has invoked `process.exit()` because argument validation failed, or a `--help` / `--version` flag was detected.

fix

First, check if your CLI was invoked with `-h`, `--help`, `-v`, or `--version`. If not, verify your `minArguments` setting and the number of arguments provided to the CLI. If you want to prevent automatic exiting by `simple-bin-help`, set the `noExit: true` option in its configuration object.

Upgrade

Version history

1.8.0latest on npm

Audit

Dependencies

update-notifierrequiredUsed to automatically check for and notify users about new package versions.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/bahmutov/simple-bin-help ↗

packagehttps://www.npmjs.com/package/simple-bin-help ↗