[](https://www.npmjs.com/package/peowly)
[](https://www.npmjs.com/package/peowly)
[](https://github.com/neostandard/neostandard)
[](https://github.com/voxpelli/badges-cjs-esm)
[](https://github.com/voxpelli/types-in-js)
[](https://mastodon.social/@voxpelli)
[`meow`](https://github.com/sindresorhus/meow) inspired [`parseArgs()`](https://nodejs.org/api/util.html#utilparseargsconfig) based CLI parser. Also contains help text helpers
## Usage
### Simple
```javascript
const { flags } = peowly({
options: {
fix: {
description: 'Fixes stuff',
type: 'boolean',
},
},
});
```
### Example
See [`example/basic.js`](./example/basic.js)
## API
### peowly()
```ts
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`](#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`](#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`](#helpmessageinfo)
* `version` - _string_ - the version to show on `--version` (defaults to `pkg.version`)
#### Parser Options
* `args` - _string[]_ - same as for [`parseArgs()`](https://nodejs.org/api/util.html#utilparseargsconfig) (defaults to `process.argv` with `execPath` and `filename` removed)
* `options` - _`Flags`_ - superset of that of [`parseArgs()`](https://nodejs.org/api/util.html#utilparseargsconfig). 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()
```ts
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
```ts
import type { AnyFlag } from 'peowly';
interface HelpListBasicItem {
listGroup?: string;
description: string;
}
type HelpListItem = AnyFlag | HelpListBasicItem;
type HelpListBasic = Record;
type HelpList = Record;
```
### defaultFlags
Contains the definition of the two default flags `--help` and `--version`.
### formatHelpList()
Most of the time you should use [`formatHelpMessage()`](#formathelpmessage) instead.
```ts
function formatHelpList(list: HelpList, indent: number, options?: HelpListOptions): string
```
#### Arguments
* `list` - _HelpList_ - the list that represents the flags, see types in [`formatHelpMessage()`](#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()
```ts
function formatFlagList(list: HelpList, indent: number, options?: HelpListOptions): string
```
Same as [`formatHelpList()`](#formathelplist) but with the [`keyPrefix`](#helplistoptions) option defaulting to `'--'`.
### formatGroupedHelpList()
```ts
formatGroupedHelpList(list: HelpList, indent: number, options?: HelpListGroupOptions): string
```
Similar to [`formatHelpList()`](#formathelplist) but prints help items grouped and has some additional options to support it in that.
#### HelpListGroupOptions
Same as [`HelpListOptions`](#helplistoptions) but with these additional options:
* `alignWithinGroups` - _boolean_ - when set (and unless [`fixedPadName`](#helplistoptions) 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()
```ts
formatGroupedFlagList(list: HelpList, indent: number, options?: HelpListGroupOptions): string
```
Same as [`formatGroupedHelpList()`](#formatgroupedhelplist) but with the [`keyPrefix`](#helplistoptions) option defaulting to `'--'` and [`defaultGroup`](#helplistgroupoptions) defaulting to `'Options'`.
## Similar modules
* [`argsclopts`](https://github.com/bcomnes/argsclopts) - also concerned with generating help texts for `parseArgs()`
* [`meow`](https://github.com/sindresorhus/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`](https://github.com/voxpelli/meow-with-subcommands) - a companion module to `meow` that provides the same help functionality as this module
* [`peowly-commands`](https://github.com/voxpelli/peowly-commands) - a companion module to this module that makes it on par with `meow-with-subcommands`
## See also
* [`parseArgs()`](https://nodejs.org/api/util.html#utilparseargsconfig) - the node.js API this module is built around. Available since `v18.3.0` and `v16.17.0`, non-experimental since `v20.0.0`.
