{"id":24642511,"url":"https://github.com/luciancooper/help-output","last_synced_at":"2026-05-16T08:37:57.049Z","repository":{"id":57262672,"uuid":"346225155","full_name":"luciancooper/help-output","owner":"luciancooper","description":"Help message formatter for command line programs","archived":false,"fork":false,"pushed_at":"2021-05-21T04:44:43.000Z","size":284,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-25T04:11:36.352Z","etag":null,"topics":["cli","help","nodejs","usage"],"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/luciancooper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-10T03:57:47.000Z","updated_at":"2023-02-13T18:11:50.000Z","dependencies_parsed_at":"2022-09-01T04:26:46.119Z","dependency_job_id":null,"html_url":"https://github.com/luciancooper/help-output","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/luciancooper/help-output","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luciancooper%2Fhelp-output","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luciancooper%2Fhelp-output/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luciancooper%2Fhelp-output/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luciancooper%2Fhelp-output/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luciancooper","download_url":"https://codeload.github.com/luciancooper/help-output/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luciancooper%2Fhelp-output/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267858704,"owners_count":24155941,"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","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","help","nodejs","usage"],"created_at":"2025-01-25T13:12:00.736Z","updated_at":"2026-05-16T08:37:57.009Z","avatar_url":"https://github.com/luciancooper.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"#\"\u003e\n    \u003cimg src=\"media/logo.svg\" alt=\"help-output\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eCreate beautifully formatted help messages for your command line programs\u003c/b\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/help-output\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/help-output?logo=npm\u0026style=for-the-badge\" alt=\"npm\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/luciancooper/help-output/actions/workflows/ci.yml\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/workflow/status/luciancooper/help-output/CI?logo=github\u0026style=for-the-badge\" alt=\"ci\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/luciancooper/help-output\"\u003e\n    \u003cimg src=\"https://img.shields.io/codecov/c/gh/luciancooper/help-output?logo=codecov\u0026style=for-the-badge\" alt=\"coverage\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"#License\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/luciancooper/help-output?color=yellow\u0026style=for-the-badge\" alt=\"license\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nPairs nicely with libraries like [`minimist`](https://github.com/substack/minimist) and [`yargs-parser`](https://github.com/yargs/yargs-parser) that are great for parsing command line arguments but don't generate help messages.\n\n## Installation\n\nInstall with `npm`:\n\n```bash\nnpm install help-output\n```\n\nOr with `yarn`:\n\n```bash\nyarn add help-output\n```\n\n## Usage\n\nImport the `helpOutput` function and pass it a configuration object with the name of your program, positional arguments, and options:\n\n```js\nconst helpOutput = require('help-output')\n\nconst message = helpOutput({\n    name: 'mycli',\n    description: 'A cli program that does something useful',\n    positional: [{\n        name: 'arg',\n        description: 'A required positional argument',\n    }],\n    options: [{\n        name: 'log',\n        arg: 'lvl',\n        conflicts: ['q', 'd'],\n        description: \"Set logging level ('error', 'warning', 'debug', or 'silent')\",\n    }, {\n        name: 'quiet',\n        alias: 'q',\n        description: \"Silence console output, equivalent to setting --log='silent'\",\n    }, {\n        name: 'debug',\n        alias: 'd',\n        conflicts: 'quiet',\n        description: \"Log verbose output, equivalent to setting --log='debug'\",\n    }, {\n        name: 'help',\n        alias: 'h',\n        preferAlias: true,\n        description: 'Display this help message',\n    }, {\n        name: 'version',\n        alias: 'v',\n        preferAlias: true,\n        description: 'Display program version',\n    }],\n}, { width: 80 });\n\nconsole.log(message);\n```\n\nPositional arguments and option flags are formatted into columns, and a git style usage section is automatically generated based on the information provided about them:\n\n\u003cp align=\"center\"\u003e\n  \u003ca id=\"example-usage\" href=\"#example-usage\"\u003e\n    \u003cimg src=\"media/example.svg\" alt=\"example\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## API\n\n### `helpOutput(config, [options])`\n\nA function that takes a `config` object and `options` object as arguments, and returns a help output message `string`. The `config` object is where you specify the arguments and options that will be displayed in the help output message, while the optional `options` object gives you some control over how the message will be formatted. \n\n#### Configuration\n\n\u003e **Note:** configuration validation is strict - an error will be thrown if any properties do not conform to the schema detailed below.\n\n##### `config.name`\n\nType: `string`\n\nThe name of your cli program. If left unspecified, a name will be inferred from `process.argv`.\n\n##### `config.title`\n\nType: `string`\n\nAn optional title to display at the top of the outputted help message. It can it can include two placeholder strings, `%name` and `%version`, which will be replaced by the values of `config.name` and `config.version`, respectively.\n\n##### `config.version`\n\nType: `string`\n\nThe programs current version. This field only necessary if `config.title` is set and includes the `%version` placeholder string.\n\n##### `config.description`\n\nType: `string`\n\nAn optional description of what the program does. If specified, it will be displayed at the top of the outputted help message, just below `config.title`.\n\n##### `config.positional`\n\nType: `Object[]`\n\nAn array of objects specifying your programs positional arguments. They will be displayed in the order they are specified. Each argument spec object can contain the following properties:\n\n   * `name` - The name of the positional argument (**required**).\n   * `description` - A description of the argument. This property is not strictly required, but is strongly encouraged.\n   * `required` - A boolean (defaults to `true`) indicating whether the argument is required.\n   * `variadic` - A boolean (defaults to `false`) indicating whether the argument is variadic.\n\n##### `config.options`\n\nType: `Object[]`\n\nAn array of objects specifying your programs option flags. They will be displayed in the order they are specified. Each option spec object can contain the following properties:\n\n   * `name` - The name of the option (**required**).\n   * `description` - A description of the option. This property is not strictly required, but is strongly encouraged.\n   * `required` - A boolean (defaults to `false`) indicating whether the option is required.\n   * `arg` - A string, object, or array of either specifying one or more positional arguments the option takes. Object specs use the same structure as those specified in `config.positional` (minus the `description` field). String specs are equivalent to specifiying an object containing only a `name` property.\n   * `alias` - A string or array of strings specifying any aliases for the option.\n   * `preferAlias` - A boolean or string indicating that the options alias name should be used in the program usage section that gets generated. If value is a string, it must be one of the alias names specified for the option. Defaults to `false`.\n   * `dependsOn` - The name of another option that this option depends on. Make sure that the option referenced here has been configured, otherwise an error will be thrown. References to alias names are allowed.\n   * `conflicts` - Another option name or array of names that this option conflicts with. Make sure that these option names specified here reference other options that have been configured, otherwise an error will be thrown. References to alias names are allowed.\n\n**Note:** relationships specified by the `dependsOn` and `conflicts` fields are reflected in the program usage section that is automatically generated. Check out the [examples](#Examples) section below for more information.\n\n#### Options\n\n##### `options.width`\n\nType: `number`\n\nCharacter width to wrap the help output message to, defaults to the width of `process.stdout`.\n\n##### `options.spacing`\n\nType: `number`\n\nSize of the gap between table columns, default is `2`.\n\n##### `options.indent`\n\nType: `number`\n\nHow much to indent the content of each section on the left side, defaults to the value of `options.spacing`.\n\n##### `options.color`\n\nType: `boolean`\n\nWhether the returned help message string should be colorized, default is `true`.\n\n##### `options.styles`\n\nType: `Object`\n\nAnsi colorization customizations This option is only relevant if `options.color` is `true`. Must be an object that maps *style selector ids* to *ansi style values*. The following are valid style selector ids that target different components of the help output string:\n\n * `'positional'` - selector id for positional arguments (default style is `'yellow'`).\n * `'option'` - selector id for option names (default style is `'green'`).\n * `'header'` - selector id for section headers (default style is `'bold.underline'`).\n\nSpecifying `null` or `''` for a selector id will result in no style being applied. Check out [`ansi-styles`](https://github.com/chalk/ansi-styles) for a list of valid style values, (multiple values must be separated by a `'.'`, or supplied as an array).\n\n## Examples\n\nAdditional information specified about a program option, such as whether it is required or if it depends on another option, is reflected in the program usage section that is included in the returned help message.\n\nThe following example demonstrates how using the `required` and `dependsOn` fields will affect the resulting message.\n\n```js\nconst message = helpOutput({\n    name: 'mycli',\n    options: [{\n        name: 'foo',\n        required: true,\n        description: 'A required flag',\n    }, {\n        name: 'bar',\n        description: 'An optional flag',\n    }, {\n        name: 'baz',\n        description: 'Another optional flag',\n    }, {\n        name: 'qux',\n        dependsOn: 'baz',\n        description: 'A flag that can only be specified if --baz is present',\n    }],\n});\n```\n\nThe generated usage will indicate that the `--foo` flag must be present, the `--bar` and `--baz` flags are optional, and the `--qux` flag is allowed only if the `--baz` flag is present:\n\n\u003cp align=\"center\"\u003e\n  \u003ca id=\"examples-basic\" href=\"#examples-basic\"\u003e\n    \u003cimg src=\"media/examples-basic.svg\" alt=\"examples-basic\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n### Mutually Exclusive Groups\n\nOption conflicts specified via the `conflicts` field will be indicated in the generated usage in form of mutually exclusive groups.\nGroups with required members are enclosed in parentheses, while groups with optional members are enclosed in brackets.\n\n\u003e **Note:** all options that make up a mutually exclusive group must be either optional or required - attempting to have a mutually exclusive group with a mixture of optional and required members will result in an error being thrown.\n\nIn the following example, the `--foo` and `--bar` flags form one group, and the `--baz` and `--qux` flags form another. \n\n```js\nconst message = helpOutput({\n    name: 'mycli',\n    options: [{\n        name: 'foo',\n        required: true,\n        conflicts: 'bar',\n        description: 'Part of a required mutually exclusive group with --bar',\n    }, {\n        name: 'bar',\n        required: true,\n        description: 'Part of a required mutually exclusive group with --foo',\n    }, {\n        name: 'baz',\n        conflicts: 'qux',\n        description: 'Part of an optional mutually exclusive group with --qux',\n    }, {\n        name: 'qux',\n        description: 'Part of an optional mutually exclusive group with --baz',\n    }],\n});\n```\n\nThe generated usage will indicate that either the `--foo` or the `--bar` flag *must* be preset, and that either the `--baz` or the `--qux` flag may optionally be present:\n\n\u003cp align=\"center\"\u003e\n  \u003ca id=\"examples-me-groups\" href=\"#examples-me-groups\"\u003e\n    \u003cimg src=\"media/examples-me-groups.svg\" alt=\"examples-me-groups\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n### Partially Exclusive Groups\n\nIt is not a requirement that every member of a mutually exclusive group conflict with every other option in that group.\n\nIn the following example `--foo` conflicts with the `--bar`, `--baz`, and `--qux` flags, but the latter three flags do not conflict with each other.\n\n```js\nconst message = helpOutput({\n    name: 'mycli',\n    options: [{\n        name: 'foo',\n        conflicts: ['bar', 'baz', 'qux'],\n        description: 'Cannot be specified alongside --bar, --baz, or --qux',\n    }, {\n        name: 'bar',\n        description: 'Can be specified alongside --baz and --qux, but not --foo',\n    }, {\n        name: 'baz',\n        description: 'Can be specified alongside --bar and --qux, but not --foo',\n    }, {\n        name: 'qux',\n        description: 'Can be specified alongside --bar and --baz, but not --foo',\n    }],\n});\n```\n\nThe generated usage will indicate that either the `--foo` flag may be present, or any combination of the `--bar`, `--baz`, and `--qux` flags may be present:\n\n\u003cp align=\"center\"\u003e\n  \u003ca id=\"examples-pe-groups\" href=\"#examples-pe-groups\"\u003e\n    \u003cimg src=\"media/examples-pe-groups.svg\" alt=\"examples-pe-groups\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Development\n\nContributions are welcome!\n\nTo report a bug or request a feature, please [open a new issue](../../issues/new).\n\n### Running Tests \n\nInstall project dependencies and run the test suite with the following command:\n\n```bash\nyarn \u0026\u0026 yarn test\n```\n\nTo generate coverage reports, run:\n\n```bash\nyarn test --coverage\n```\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluciancooper%2Fhelp-output","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluciancooper%2Fhelp-output","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluciancooper%2Fhelp-output/lists"}