peowly v1.3.2

meow inspired parseArgs() based CLI parser. Also contains help text helpers

Usage

Simple

const { flags } = peowly({
  options: {
    fix: {
      description: 'Fixes stuff',
      type: 'boolean',
    },
  },
});

Example

See example/basic.js

API

peowly()

peowly(options): { flags, input, remainderArgs, showHelp }

Meta Options

• description - string | false - a description that will be prefixed to the help text (defaults to pkg.description, deactivated by false)
• examples - see HelpMessageInfo
• help - string - the help text to show on --help, preferably generated with formatHelpMessage() (defaults to being rendered with formatHelpMessage() using available data)
• indent - see HelpMessageInfo
• name - string - the name of the CLI command. Used by a couple of other defaults. (defaults to the first key in pkg.bin and else to pkg.name)
• pkg - PackageJsonLike - a package.json which some meta data can be derived from
• processTitle - string | false - sets the process.title to this (defaults to name, deactivated by false)
• usage - see HelpMessageInfo
• version - string - the version to show on --version (defaults to pkg.version)

Parser Options

• args - string[] - same as for parseArgs() (defaults to process.argv with execPath and filename removed)
• options - Flags - superset of that of parseArgs(). Every option / flag is expected to have a description string property in addition to what parseArgs() require and they may have a listGroup string property as well
• returnRemainderArgs - boolean - if set, then all parts of args that doesn't match a flag in options will be returned as remainderArgs, which can eg. be forwarded to another parser

formatHelpMessage()

formatHelpMessage(name: string, info?: HelpMessageInfo): string

Arguments

• name - string - the name of the CLI command

HelpMessageInfo

• aliases - HelpListBasic - list of help items to join with commands but with group name defaulting to 'Aliases' and other group names being prefixed with ' Aliases'
• commands - HelpListBasic - list of help items to add prior to the flags list and with a default group name of 'Commands'
• examples - (string | { prefix?: string, suffix?: string })[] - will be added as examples on individual lines prefixed with $ ${name} or, if provided as prefix and suffix, then the prefix will go inbetween $ and the name and the suffix after that, separated by spaces
• flags - HelpList - the flags to output in the help, compatible with Flags
• indent - number - the number of spaces to indent the help text with (defaults to 2)
• noDefaultFlags - boolean - excludes the default flags from the help text
• usage - string - what, if anything, that follows the $ ${name} in 'Usage' headline in the initial help text

Types

import type { AnyFlag } from 'peowly';

interface HelpListBasicItem {
  listGroup?: string;
  description: string;
}

type HelpListItem = AnyFlag | HelpListBasicItem;

type HelpListBasic = Record<string, HelpListBasicItem>;

type HelpList = Record<string, HelpListItem | string>;

defaultFlags

Contains the definition of the two default flags --help and --version.

formatHelpList()

Most of the time you should use formatHelpMessage() instead.

function formatHelpList(list: HelpList, indent: number, options?: HelpListOptions): string

Arguments

• list - HelpList - the list that represents the flags, see types in formatHelpMessage()
• indent - number - how far to indent the list

HelpListOptions

• fixedPadName - boolean - when set, padName will be treated as a fixed rather than minimum padding
• keyPrefix - string - a prefix for the name
• padName - number - the minimum padding between names and descriptions
• shortFlagPrefix - string - a prefix for a shortFlag (defaults to '-')

formatFlagList()

function formatFlagList(list: HelpList, indent: number, options?: HelpListOptions): string

Same as formatHelpList() but with the keyPrefix option defaulting to '--'.

formatGroupedHelpList()

formatGroupedHelpList(list: HelpList, indent: number, options?: HelpListGroupOptions): string

Similar to formatHelpList() but prints help items grouped and has some additional options to support it in that.

HelpListGroupOptions

Same as HelpListOptions but with these additional options:

• alignWithinGroups - boolean - when set (and unless fixedPadName is set) the padding between name and description will be calculated within each group instead of across all groups
• defaultGroupName - string - the default group name where all items that have no explicit group belonging will be placed (defaults to 'Default')
• defaultGroupOrderFirst - boolean - if set the default group is added at the start rather than at the end

formatGroupedFlagList()

formatGroupedFlagList(list: HelpList, indent: number, options?: HelpListGroupOptions): string

Same as formatGroupedHelpList() but with the keyPrefix option defaulting to '--' and defaultGroup defaulting to 'Options'.

Similar modules

• argsclopts - also concerned with generating help texts for parseArgs()
• meow - a more full fledged alternative and name inspiration (p as in parseArgs, eow as in meow, ly to avoid being perceived as a typejacking)
• meow-with-subcommands - a companion module to meow that provides the same help functionality as this module
• peowly-commands - a companion module to this module that makes it on par with meow-with-subcommands

See also

• parseArgs() - the node.js API this module is built around. Available since v18.3.0 and v16.17.0, non-experimental since v20.0.0.