Generate formatted help text for Node.js CLIs.

help doesn't attempt to parse arguments as some more comprehensive CLI frameworks do. Instead, it aims to be an unopinionated primitive that can be used as a stand-alone utility or as a building block within a more comprehensive CLI framework

Features

• A simple and intuitive functional API
• Flexibility: Makes no assumptions about your CLI's argument scheme
• Dynamic line wrapping based on terminal width
• Extensible built-in functions
• Full TypeScript type support

Install

pnpm install @theurgi/help

Usage

Extended examples

• Coloring with chalk
• Extending built-in functions
• Cloning Astro's help text

Basic example

import { help, heading, paragraph, space, table } from '@theurgi/help'

console.log(
  help({
    display: [
      paragraph('My awesome CLI'),
      space(),
      heading('Usage'),
      paragraph('$ cli <command> [options]', { indentLevel: 1 }),
      space(),
      heading('Commands'),
      table([
        ['create', 'Create something'],
        ['update', 'Update something'],
      ]),
      space(),
      heading('Options'),
      table([
        ['-h, --help', 'Show help'],
        ['-v, --version', 'Show version'],
      ]),
    ],
  })
)

API

Exports

Functions

• help
• heading
• paragraph
• space
• table

Types

• Generator
• HeadingOptions
• HelpConfig
• HelpOptions
• IndentLevel
• IndentSpaces
• ParagraphOptions
• RenderFunction
• TableAlignment
• TableOptions

Functions

help

▸ help(helpConfig): string

Generate formatted help text for Node.js CLIs.

Parameters

Name	Type	Description
helpConfig	HelpConfig	The help configuration.

Returns

string

---

heading

▸ heading(text, options?): RenderFunction

Generate a heading.

Parameters

Name	Type	Description
text	string	The heading text.
options?	Partial<HeadingOptions>	The heading options.

Returns

RenderFunction

---

paragraph

▸ paragraph(text, options?): RenderFunction

Generate a paragraph.

Parameters

Name	Type	Description
text	string	The paragraph text.
options?	Partial<ParagraphOptions>	The paragraph options.

Returns

RenderFunction

---

space

▸ space(newlines?): RenderFunction

Generate blank newlines.

Parameters

Name	Type	Description	Default
newlines?	number	The number of newlines to render.	1

Returns

RenderFunction

---

table

▸ table(data, options?): RenderFunction

Generate a 2 column table.

Parameters

Name	Type	Description
data	[string, string][]	An array of string tuples where data[n][0] is typically a CLI command or option and data[n][1] is typically a description of data[n][0].
options?	Partial<TableOptions>	The table options.

Returns

RenderFunction

Type Aliases

Generator

Ƭ Generator<T>: (...parameters: Parameters<T>) => RenderFunction

NOTE: A Generator in the context of help has no relation to JavaScript Generators.

A Generator is a function that is called inside the HelpConfig.display array of the main help function and returns a RenderFunction.

Built-in Generators

• heading
• paragraph
• space
• table

Type parameters

Name	Type
T	extends (...parameters: any) => RenderFunction

Type declaration

▸ (...parameters): RenderFunction

Parameters

Name	Type
...parameters	Parameters<T>

Returns

RenderFunction

---

HeadingOptions

Ƭ HeadingOptions: Object

Type declaration

Name	Type	Description	Default
indentLevel	IndentLevel	The level of indentation for the heading.	0

---

HelpConfig

Ƭ HelpConfig: Object

Type declaration

Name	Type	Description
display	RenderFunction[]	An array in which to call Generator functions to render portions of the help text.
options?	Partial<HelpOptions>	Global options for the help text.

---

HelpOptions

Ƭ HelpOptions: Object

Type declaration

Name	Type	Description	Default
indentSpaces	IndentSpaces	The number of spaces used for each indentation level.	2
maxWidth	number	The maximum width of the help text in characters.	The terminal width.

---

IndentLevel

Ƭ IndentLevel: number

The number of times to left pad a string with IndentSpaces spaces.

---

IndentSpaces

Ƭ IndentSpaces: number

The number of spaces per IndentLevel.

---

ParagraphOptions

Ƭ ParagraphOptions: Object

Type declaration

Name	Type	Description	Default
indentLevel	IndentLevel	The level of indentation for the paragraph.	0

---

RenderFunction

Ƭ RenderFunction: (helpOptions: HelpOptions) => string

Type declaration

▸ (helpOptions): string

The type of function that must be returned by a Generator. This function will be called with global HelpOptions by the main help function to render a formatted string.

Parameters

Name	Type
helpOptions	HelpOptions

Returns

string

---

TableAlignment

Ƭ TableOptions: 'center' | 'justify' | 'left' | 'right'

The horizontal alignment of a table column.

---

TableOptions

Ƭ TableOptions: Object

Type declaration

Name	Type	Description	Default
columnGap	number	The number of spaces between columns.	2
indentLevel	IndentLevel	The level of indentation for the table.	1
leftColAlign	TableAlignment	The alignment of the left column.	'left'
rightColAlign	TableAlignment	The alignment of the right column	'left'