{"id":16146558,"url":"https://github.com/voxpelli/peowly","last_synced_at":"2025-09-13T00:32:41.497Z","repository":{"id":232405765,"uuid":"783885577","full_name":"voxpelli/peowly","owner":"voxpelli","description":"meow inspired parseArgs() based CLI parser. Also contains help text helpers","archived":false,"fork":false,"pushed_at":"2024-07-29T03:50:27.000Z","size":52,"stargazers_count":2,"open_issues_count":7,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-08-09T09:16:43.706Z","etag":null,"topics":["cli","cli-parser","nodejs","parseargs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voxpelli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-08T19:10:23.000Z","updated_at":"2024-08-15T04:38:28.841Z","dependencies_parsed_at":"2024-04-15T13:47:24.139Z","dependency_job_id":"329ae17d-07c3-4b17-b9ce-8f1ebc306557","html_url":"https://github.com/voxpelli/peowly","commit_stats":null,"previous_names":["voxpelli/peowly"],"tags_count":9,"template":false,"template_full_name":"voxpelli/node-module-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpelli%2Fpeowly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpelli%2Fpeowly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpelli%2Fpeowly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpelli%2Fpeowly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voxpelli","download_url":"https://codeload.github.com/voxpelli/peowly/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232802583,"owners_count":18578688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cli-parser","nodejs","parseargs"],"created_at":"2024-10-10T00:20:31.467Z","updated_at":"2025-09-13T00:32:41.466Z","avatar_url":"https://github.com/voxpelli.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg\n    src=\"peowly.svg\"\n    width=\"512\"\n    height=\"auto\"\n    alt=\"peowly\"\n  /\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![npm version](https://img.shields.io/npm/v/peowly.svg?style=flat)](https://www.npmjs.com/package/peowly)\n[![npm downloads](https://img.shields.io/npm/dm/peowly.svg?style=flat)](https://www.npmjs.com/package/peowly)\n[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-7fffff?style=flat\u0026labelColor=ff80ff)](https://github.com/neostandard/neostandard)\n[![Module type: ESM](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)\n[![Types in JS](https://img.shields.io/badge/types_in_js-yes-brightgreen)](https://github.com/voxpelli/types-in-js)\n[![Follow @voxpelli@mastodon.social](https://img.shields.io/mastodon/follow/109247025527949675?domain=https%3A%2F%2Fmastodon.social\u0026style=social)](https://mastodon.social/@voxpelli)\n\n\u003c/div\u003e\n\n[`meow`](https://github.com/sindresorhus/meow) inspired [`parseArgs()`](https://nodejs.org/api/util.html#utilparseargsconfig) based CLI parser. Also contains help text helpers\n\n## Usage\n\n### Simple\n\n```javascript\nconst { flags } = peowly({\n  options: {\n    fix: {\n      description: 'Fixes stuff',\n      type: 'boolean',\n    },\n  },\n});\n```\n\n### Example\n\nSee [`example/basic.js`](./example/basic.js)\n\n## API\n\n### peowly()\n\n```ts\npeowly(options): { flags, input, remainderArgs, showHelp }\n```\n\n#### Parser Options\n\nThese options control how command-line arguments are parsed and define the CLI flags/options your tool accepts:\n\n* `args` - _string[]_ - same as for [`parseArgs()`](https://nodejs.org/api/util.html#utilparseargsconfig) (defaults to `process.argv` with `execPath` and `filename` removed)\n* `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\n* `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\n\n#### Meta Options\n\nThese options configure help text, process metadata, and other CLI tool presentation:\n\n* `description` - _string_ | _false_ - a description that will be prefixed to the help text (defaults to `pkg.description`, deactivated by `false`)\n* `examples` - see [`HelpMessageInfo`](#helpmessageinfo)\n* `help` - _string_ - the help text to show on `--help`, preferably generated with `formatHelpMessage()` (defaults to being rendered with `formatHelpMessage()` using available data)\n* `indent` - see [`HelpMessageInfo`](#helpmessageinfo)\n* `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`)\n* `pkg` - _`PackageJsonLike`_ - a `package.json` which some meta data can be derived from\n* `processTitle` - _string_ | _false_ - sets the `process.title` to this (defaults to `name`, deactivated by `false`)\n* `usage` - see [`HelpMessageInfo`](#helpmessageinfo)\n* `version` - _string_ - the version to show on `--version` (defaults to `pkg.version`)\n\n### formatHelpMessage()\n\n```ts\nformatHelpMessage(name: string, info?: HelpMessageInfo): string\n```\n\n#### Arguments\n\n* `name` - _string_ - the name of the CLI command\n\n#### HelpMessageInfo\n\n* `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'`\n* `commands` - _`HelpListBasic`_ - list of help items to add prior to the flags list and with a default group name of `'Commands'`\n* `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\n* `flags` - _`HelpList`_ - the flags to output in the help, compatible with _`Flags`_\n* `indent` - _number_ - the number of spaces to indent the help text with (defaults to `2`)\n* `noDefaultFlags` - _boolean_ - excludes the default flags from the help text\n* `usage` - _string_ - what, if anything, that follows the `$ ${name}` in `'Usage'` headline in the initial help text\n\n#### Types\n\n```ts\nimport type { AnyFlag } from 'peowly';\n\ninterface HelpListBasicItem {\n  listGroup?: string;\n  description: string;\n}\n\ntype HelpListItem = AnyFlag | HelpListBasicItem;\n\ntype HelpListBasic = Record\u003cstring, HelpListBasicItem\u003e;\n\ntype HelpList = Record\u003cstring, HelpListItem | string\u003e;\n```\n\n### defaultFlags\n\nContains the definition of the two default flags `--help` and `--version`.\n\n### formatHelpList()\n\nMost of the time you should use [`formatHelpMessage()`](#formathelpmessage) instead.\n\n```ts\nfunction formatHelpList(list: HelpList, indent: number, options?: HelpListOptions): string\n```\n\n#### Arguments\n\n* `list` - _HelpList_ - the list that represents the flags, see types in [`formatHelpMessage()`](#formathelpmessage)\n* `indent` - _number_ - how far to indent the list\n\n#### HelpListOptions\n\n* `fixedPadName` - _boolean_ - when set, `padName` will be treated as a fixed rather than minimum padding\n* `keyPrefix` - _string_ - a prefix for the name\n* `padName` - _number_ - the minimum padding between names and descriptions\n* `shortFlagPrefix` - _string_ - a prefix for a `shortFlag` (defaults to `'-'`)\n\n### formatFlagList()\n\n```ts\nfunction formatFlagList(list: HelpList, indent: number, options?: HelpListOptions): string\n```\n\nSame as [`formatHelpList()`](#formathelplist) but with the [`keyPrefix`](#helplistoptions) option defaulting to `'--'`.\n\n### formatGroupedHelpList()\n\n```ts\nformatGroupedHelpList(list: HelpList, indent: number, options?: HelpListGroupOptions): string\n```\n\nSimilar to [`formatHelpList()`](#formathelplist) but prints help items grouped and has some additional options to support it in that.\n\n#### HelpListGroupOptions\n\nSame as [`HelpListOptions`](#helplistoptions) but with these additional options:\n\n* `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\n* `defaultGroupName` - _string_ - the default group name where all items that have no explicit group belonging will be placed (defaults to `'Default'`)\n* `defaultGroupOrderFirst` - _boolean_ - if set the default group is added at the start rather than at the end\n\n### formatGroupedFlagList()\n\n```ts\nformatGroupedFlagList(list: HelpList, indent: number, options?: HelpListGroupOptions): string\n```\n\nSame as [`formatGroupedHelpList()`](#formatgroupedhelplist) but with the [`keyPrefix`](#helplistoptions) option defaulting to `'--'` and [`defaultGroup`](#helplistgroupoptions) defaulting to `'Options'`.\n\n\u003c!-- ## Used by\n\n* [`example`](https://example.com/) - used by this one to do X and Y --\u003e\n\n## Similar modules\n\n* [`argsclopts`](https://github.com/bcomnes/argsclopts) - also concerned with generating help texts for `parseArgs()`\n* [`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)\n* [`meow-with-subcommands`](https://github.com/voxpelli/meow-with-subcommands) - a companion module to `meow` that provides the same help functionality as this module\n* [`peowly-commands`](https://github.com/voxpelli/peowly-commands) - a companion module to this module that makes it on par with `meow-with-subcommands`\n\n## See also\n\n* [`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`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpelli%2Fpeowly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoxpelli%2Fpeowly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpelli%2Fpeowly/lists"}