cli-usage

0.1.10 verified Sat Apr 25 auth: no javascript maintenance

A lightweight Node.js package (v0.1.10) that reads a Markdown file or string and prints formatted usage text to the console when CLI help flags (-h, --help) are passed. It can automatically locate a usage.md file relative to the entry script or accept custom paths and Markdown strings. The package uses the 'marked' library for Markdown-to-terminal conversion. Last updated with minor dependency bumps, it is simple and dependency-light, but lacks active maintenance. Key differentiators: zero-config auto-detection of help flags and usage.md, plus a .get() API to retrieve compiled text without auto-printing.

Common errors

error TypeError: usage is not a function ↓

cause Using ES module import with 'import usage from "cli-usage"' in a CommonJS environment or vice versa.

fix

Use require('cli-usage') and assign to a variable (var usage = require('cli-usage');).

error ENOENT: no such file or directory, open 'usage.md' ↓

cause Calling usage() without a path and no usage.md exists in script's directory.

fix

Specify a full or relative path to a Markdown file, e.g., usage('./path/to/usage.md').

error ReferenceError: usage is not defined ↓

cause Forgetting to require the package or scoping issue.

fix

Add var usage = require('cli-usage'); at the top of your file.

Warnings

deprecated Package hasn't received significant updates since 2016. Dependency 'marked' is outdated. ↓

fix Consider alternatives like 'commander' help or 'caporal' for CLI argument parsing with built-in help.

gotcha The usage function listens for help flags globally and may conflict with other help handling. ↓

fix Use the .get() method manually and implement your own flag parsing instead of relying on the automatic behavior.

gotcha If no argument is passed, it tries to find 'usage.md' relative to process.argv[1] (the script). If not found, nothing happens silently. ↓

fix Always pass a file path or Markdown string explicitly.

breaking Help flag detection triggers process.exit(0); this can be unexpected in a library context. ↓

fix Do not use in non-CLI modules. Use .get() to retrieve text without side effects.

Install

npm install cli-usage

yarn add cli-usage

pnpm add cli-usage

Imports

default (usage function)
wrong
```
import usage from 'cli-usage';
```
correct
```
var usage = require('cli-usage');
```
Package uses CommonJS only; ESM import may fail unless using a bundler or Node.js with --experimental-require-module.

.get() method

wrong

import { get } from 'cli-usage';

correct

var usage = require('cli-usage');
var text = usage.get('# markdown');

.get() is a method on the exported function object, not a separate named export.

usage function with argument
wrong
```
usage({ path: './path/to/usage.md' });
```
correct
```
var usage = require('cli-usage');
usage('./path/to/usage.md');
```
The function accepts a string (file path or Markdown content); passing an object will be ignored.

Quickstart

Demonstrates basic usage: creating a usage function that prints a Markdown string when help flags are passed, and auto-detection of usage.md file.

var usage = require('cli-usage');

// Print usage from a Markdown string when --help is passed
usage('# My CLI\n\nUsage: my-cli [options]\n\n## Options\n- `-v` Show version\n- `-h` Show help');

// Or print usage automatically from usage.md (auto-detect if no argument given)
// usage(); // looks for usage.md in script's directory