{"id":18219,"library":"cli-usage","title":"cli-usage","description":"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.","status":"maintenance","version":"0.1.10","language":"javascript","source_language":"en","source_url":"https://github.com/mikaelbr/cli-usage","tags":["javascript","CLI-Usage","Markdown","Usage","CLI","Print-Usage"],"install":[{"cmd":"npm install cli-usage","lang":"bash","label":"npm"},{"cmd":"yarn add cli-usage","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-usage","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Converts Markdown to terminal-formatted text (e.g., bold, code blocks).","package":"marked","optional":false}],"imports":[{"note":"Package uses CommonJS only; ESM import may fail unless using a bundler or Node.js with --experimental-require-module.","wrong":"import usage from 'cli-usage';","symbol":"default (usage function)","correct":"var usage = require('cli-usage');"},{"note":".get() is a method on the exported function object, not a separate named export.","wrong":"import { get } from 'cli-usage';","symbol":".get() method","correct":"var usage = require('cli-usage');\nvar text = usage.get('# markdown');"},{"note":"The function accepts a string (file path or Markdown content); passing an object will be ignored.","wrong":"usage({ path: './path/to/usage.md' });","symbol":"usage function with argument","correct":"var usage = require('cli-usage');\nusage('./path/to/usage.md');"}],"quickstart":{"code":"var usage = require('cli-usage');\n\n// Print usage from a Markdown string when --help is passed\nusage('# My CLI\\n\\nUsage: my-cli [options]\\n\\n## Options\\n- `-v` Show version\\n- `-h` Show help');\n\n// Or print usage automatically from usage.md (auto-detect if no argument given)\n// usage(); // looks for usage.md in script's directory","lang":"javascript","description":"Demonstrates basic usage: creating a usage function that prints a Markdown string when help flags are passed, and auto-detection of usage.md file."},"warnings":[{"fix":"Consider alternatives like 'commander' help or 'caporal' for CLI argument parsing with built-in help.","message":"Package hasn't received significant updates since 2016. Dependency 'marked' is outdated.","severity":"deprecated","affected_versions":">=0.1.0"},{"fix":"Use the .get() method manually and implement your own flag parsing instead of relying on the automatic behavior.","message":"The usage function listens for help flags globally and may conflict with other help handling.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always pass a file path or Markdown string explicitly.","message":"If no argument is passed, it tries to find 'usage.md' relative to process.argv[1] (the script). If not found, nothing happens silently.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Do not use in non-CLI modules. Use .get() to retrieve text without side effects.","message":"Help flag detection triggers process.exit(0); this can be unexpected in a library context.","severity":"breaking","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use require('cli-usage') and assign to a variable (var usage = require('cli-usage');).","cause":"Using ES module import with 'import usage from \"cli-usage\"' in a CommonJS environment or vice versa.","error":"TypeError: usage is not a function"},{"fix":"Specify a full or relative path to a Markdown file, e.g., usage('./path/to/usage.md').","cause":"Calling usage() without a path and no usage.md exists in script's directory.","error":"ENOENT: no such file or directory, open 'usage.md'"},{"fix":"Add var usage = require('cli-usage'); at the top of your file.","cause":"Forgetting to require the package or scoping issue.","error":"ReferenceError: usage is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}