{"id":21082274,"url":"https://github.com/olsonpm/structured-cli","last_synced_at":"2026-02-20T17:32:05.381Z","repository":{"id":80606816,"uuid":"58786895","full_name":"olsonpm/structured-cli","owner":"olsonpm","description":null,"archived":false,"fork":false,"pushed_at":"2024-09-25T23:41:46.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-10-31T09:40:05.270Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/olsonpm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","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":"2016-05-14T03:13:08.000Z","updated_at":"2024-09-25T23:41:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"60db66fb-00c5-4c61-9496-029011425dbe","html_url":"https://github.com/olsonpm/structured-cli","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/olsonpm/structured-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olsonpm%2Fstructured-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olsonpm%2Fstructured-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olsonpm%2Fstructured-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olsonpm%2Fstructured-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/olsonpm","download_url":"https://codeload.github.com/olsonpm/structured-cli/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olsonpm%2Fstructured-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29658373,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T16:33:43.953Z","status":"ssl_error","status_checked_at":"2026-02-20T16:33:43.598Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2024-11-19T20:13:30.467Z","updated_at":"2026-02-20T17:32:05.365Z","avatar_url":"https://github.com/olsonpm.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Structured CLI\n\nThis module allows you to easily create a clean command line interface. You can\nthink of it as a framework that sacrifices (arguably harmful) flexibility for\nconsistency and user-friendliness.\n\n## Table of Contents\n\n- [Why does this library exist?](#why-does-this-library-exist)\n- [Simple Example](#example)\n- [Public API](#public-api)\n\n## Why does this library exist?\n\nI believe the general purpose cli libraries out there are harmful to the\nusability of cli's in general. This library enforces structures that should\ncome by default in every cli: help, version, obvious optional vs required\narguments, a simple and predictable format `\u003centry\u003e \u003ccommand\u003e \u003carguments...\u003e`,\nenforced argument types, and simple command/argument validation.\n\n## Example\n\nAssuming you configure [the package.json bin property](https://docs.npmjs.com/files/package.json#bin)\n, `structured-cli` turns an intuitive configuration such as:\n\n```js\n// bin/hello-world.js\nrequire('structured-cli').create({\n  description: \"a simple 'hello world' cli\",\n  commands: [\n    {\n      name: 'print',\n      fn({ loudly, times }) {\n        const out = loudly ? 'HELLO WORLD!' : 'hello world'\n\n        console.log((out + '\\n').repeat(times))\n      },\n      desc: \"prints 'hello world'\",\n      args: [\n        {\n          name: 'loudly',\n          alias: 'l',\n          desc: 'print in all caps followed by an exclamation point',\n          type: 'boolean',\n        },\n        {\n          name: 'times',\n          desc: 'repeat the string a given number of times',\n          type: 'number',\n          example: '\u003ca number\u003e',\n          flags: ['require'],\n        },\n      ],\n    },\n  ],\n})\n```\n\ninto this\n\n**help**\n\n```sh\n$ hello-world --help\n\nDescription: a simple 'hello world' cli\n\nUsage\n  hello-world \u003coptional argument\u003e\n  hello-world \u003ccommand\u003e\n\nArguments\n  -h, --help      {boolean} print this\n  -v, --version   {boolean} print version of hello-world\n\nCommands\n  print           prints 'hello world'\n\nTo get help for a command, type 'hello-world \u003ccommand\u003e --help'\n```\n\n**print help**\n\n```sh\n$ hello-world print --help\n\nDescription: prints 'hello world'\n\nUsage: hello-world print [--loudly]  --times \u003ca number\u003e\n\nRequired Arguments\n  --times        {number}  repeat the string a given number of times\n\nOptional Arguments\n  -l, --loudly   {boolean} print in all caps followed by an exclamation point\n\n```\n\n**print**\n\n```sh\n$ hello-world print --times 1\nhello world\n\n$ hello-world print --times 2 --loudly\nHELLO WORLD!\nHELLO WORLD!\n\n```\n\n**invalid command handling**\n\n```sh\n$ hello-world invalid\n\nError: Invalid command 'invalid'\n\n# then displays help text\n```\n\n**invalid argument type handling**\n\n```sh\n$ hello-world print --times a\n\nError: Argument must be passed a valid number.\nArgument: --times\nValue: a\n\n# then displays help text\n```\n\n**and finally invalid argument handling**\n\n```sh\n$ hello-world print --times 1 --loudly --invalid\n\nError: Stopped parsing due to the invalid argument '--invalid'\n\n# then displays help text\n```\n\n## Public API\n\n_An asterisk (_\\*_) indicates an optional property_\n\n`require('structured-cli')` exposes one method `create` that takes a single\n[Entry](#entry) object and returns `undefined`. The `create` method handles\nargv and logs to stdout appropriately.\n\n### Entry\n\n```js\n{\n  description: \u003cstring\u003e\n  , commands: \u003can array of 'Command's\u003e\n}\n```\n\n### Command\n\n```js\n{\n  name: \u003cstring\u003e\n  , alias*: \u003ccharacter\u003e\n  , desc: \u003cstring\u003e\n  , fn: \u003cfunction taking a single 'Function Argument'\u003e\n  , args*: \u003carray of 'Command Argument's\u003e\n}\n```\n\n#### Function Argument\n\nA command's `fn` will be called with the passed validated arguments via an\nobject. The keys will be the full name of the argument mapping to their\npassed value. Refer to the hello-world example above for clarification.\n\n### Command Argument\n\n```js\n{\n  name: \u003cstring\u003e\n  , alias*: \u003ccharacter\u003e\n  , default*: \u003cstring or number depending on 'type'\u003e\n  , desc: \u003cstring\u003e\n  , example: \u003cstring\u003e\n  , flags: \u003carray of strings contained in 'Valid Argument Flags'\u003e\n  , type: \u003ceither 'boolean', 'string', or 'number'\u003e\n}\n```\n\nThe Command Arguments will pass through some validation including:\n\n- `default` cannot be declared for type 'boolean' since a boolean argument's\n  presence indicates the value 'true'. If you want it to default to true, then\n  rename the boolean to its complement.\n- `example` is required for types 'string' and 'number' because it is used\n  to create the command usage string.\n- Likewise, `example` must not be declared for type 'boolean' since an example\n  is not applicable for boolean arguments.\n\n### Valid Argument Flags\n\nCurrently the only valid flag is `require`. I expect this to grow.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folsonpm%2Fstructured-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Folsonpm%2Fstructured-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folsonpm%2Fstructured-cli/lists"}