{"id":20475199,"url":"https://github.com/appcelerator/cli-kit","last_synced_at":"2025-04-13T12:31:21.134Z","repository":{"id":17267448,"uuid":"72161505","full_name":"appcelerator/cli-kit","owner":"appcelerator","description":"Everything you need to create awesome Node.js command line interfaces","archived":false,"fork":false,"pushed_at":"2023-07-18T20:14:50.000Z","size":16438,"stargazers_count":14,"open_issues_count":5,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-14T12:10:13.943Z","etag":null,"topics":["cli","command-line-parser","nodejs"],"latest_commit_sha":null,"homepage":"","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/appcelerator.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":"2016-10-28T01:09:55.000Z","updated_at":"2024-06-18T18:26:35.600Z","dependencies_parsed_at":"2024-06-18T18:37:42.294Z","dependency_job_id":null,"html_url":"https://github.com/appcelerator/cli-kit","commit_stats":null,"previous_names":[],"tags_count":80,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appcelerator%2Fcli-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appcelerator%2Fcli-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appcelerator%2Fcli-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appcelerator%2Fcli-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appcelerator","download_url":"https://codeload.github.com/appcelerator/cli-kit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248714340,"owners_count":21149864,"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","command-line-parser","nodejs"],"created_at":"2024-11-15T15:14:57.615Z","updated_at":"2025-04-13T12:31:21.053Z","avatar_url":"https://github.com/appcelerator.png","language":"JavaScript","readme":"# cli-kit\n\nA command line application toolkit for Node.js.\n\n[![NPM Version][npm-image]][npm-url]\n[![NPM Downloads][downloads-image]][downloads-url]\n[![Build][build-image]][build-url]\n[![Deps][david-image]][david-url]\n[![Dev Deps][david-dev-image]][david-dev-url]\n\n## Features\n\n* Command line parsing\n* Support for dynamic command hierarchies\n* Auto-generated help\n* CLI template engine\n* External CLI extensions\n* Client and server for remote CLI session such as [xterm.js][xterm]\n* Automatic Node.js version enforcement\n\n## Installation\n\n\tnpm install cli-kit --save\n\n## Usage\n\n```js\nimport CLI from 'cli-kit';\n\n(async () =\u003e {\n\tconst { argv, _ } = await new CLI({\n\t\toptions: {\n\t\t\t'-f, --force': 'use the force',\n\t\t\t'--timeout [value]': {\n\t\t\t\tdesc: 'the timeout duration',\n\t\t\t\ttype: 'int'\n\t\t\t}\n\t\t}\n\t}).exec();\n\n\tconsole.log('options:', argv);\n\tconsole.log('args:', _);\n})();\n```\n\n## Architecture\n\nIn cli-kit, commands and options are grouped into \"contexts\". The main CLI instance defines the\n\"global context\". Each command defines a new context. Each context can have its own commands,\noptions, and arguments. What you end up with is a hierarchy of contexts.\n\nWhen cli-kit parses the command line arguments, it will check each argument against the global\ncontext to see if the argument can be identified as a known command, option, or argument. If it\nfinds a command, it adds the command's context to a stack and re-parses any unidentified arguments.\n\nThis allows you to create deep and dynamic hierarchies of commands, options, and arguments.\n\n## Pseudo-Terminal Support\n\ncli-kit extensions can be native binary executables or other Node.js scripts. When the extension is\na native executable, then it is executed using Node's `spawn()`. Note that spawned child processes\ndo not have a TTY and thus things like prompting will not work.\n\n## API\n\n### class `CLI`\n\nA `CLI` intance defines a global context for which you add commands, options, and arguments.\n\nExtends `Context` \u003e [`HookEmitter`](https://www.npmjs.com/package/hook-emitter).\n\n#### `constuctor(opts)`\n\n* `opts` : `Object` (optional)\n\n  Various options to initialize the `CLI` instance.\n\n##### Example\n\n```js\nconst cli = new CLI({\n\t// An array of argument definitions. They are parsed in the order they are defined.\n\targs: [\n\t\t// An argument can be as simple as its name. Wrapping the name with `\u003c` and `\u003e` signifies\n\t\t// that the argument is required.\n\t\t'\u003carg1\u003e',\n\n\t\t// To define an optional arguemnt, you can use `[` and `]`.\n\t\t'[arg2]',\n\n\t\t// Or simply omit the brackets\n\t\t'arg3',\n\n\t\t// For more options, you can specify an argument descriptor\n\t\t{\n\t\t\t// The argument name. Follows the same rules as above.\n\t\t\tname: 'arg4',\n\n\t\t\t// The argument's description to show in the help output.\n\t\t\tdesc: undefined,\n\n\t\t\t// When `true`, hides the argument from usage string in the help output.\n\t\t\thidden: false,\n\n\t\t\t// When `true`, captures all subsequent argument values into an array\n\t\t\tmultiple: false,\n\n\t\t\t// Overrides the brackets and forces the argument to be required or optional.\n\t\t\trequired: false,\n\n\t\t\t// There are several built-in types. See the \"types\" section below for more info.\n\t\t\ttype: 'string'\n\t\t},\n\n\t\t// Adding `...` will capture all subsequent argument values into an array\n\t\t'arg4...'\n\t],\n\n\t// Global flag to camel case property names derived from multi-word options/arguments.\n\t// Defaults to true, can be overwritten by the option/argument.\n\tcamelCase: true,\n\n\t// An object of command names to command descriptors.\n\tcommands: {\n\t\t'some-command': {\n\t\t\t// The action to perform when the command is parsed.\n\t\t\taction({ argv, _ }) {\n\t\t\t\tconsole.log('options:', argv);\n\t\t\t\tconsole.log('args:', _);\n\t\t\t},\n\n\t\t\t// An array of alternate command names.\n\t\t\taliases: [ 'another-command' ],\n\n\t\t\t// Command specific args. See `args` section above.\n\t\t\targs: [],\n\n\t\t\t// When `true`, camel case all option and argument names in the `argv` result.\n\t\t\tcamelCase: true,\n\n\t\t\t// An object of subcommand names to subcommand descriptors.\n\t\t\tcommands: {},\n\n\t\t\t// The command description.\n\t\t\tdesc: undefined,\n\n\t\t\t// When `true`, hides the command from the help output.\n\t\t\thidden: false,\n\n\t\t\t// An object of option formats to option descriptors. See the `options` section below.\n\t\t\toptions: {},\n\n\t\t\t// The command name to display in the help output. Defaults to the command name.\n\t\t\ttitle: undefined\n\t\t}\n\t},\n\n\t// The default command `exec()` should run if no command was found during parsing.\n\t// If `help` is `true` and no default command is specified, it will default to displaying the\n\t// help screen. If you want help, but do not want to default to the help command, then set the\n\t// `defaultCommand` to `null`.\n\tdefaultCommand: undefined,\n\n\t// The CLI description to print on the help screen between the usage and commands/options/args.\n\tdesc: undefined,\n\n\t// Adds the `-h, --help` to the global flags and enables the auto-generated help screen.\n\t// Defaults to `true`.\n\thelp: true,\n\n\t// The exit code to return when the help screen is displayed. This is useful if you want to\n\t// force the program to exit if `--help` is specified and the user is chaining commands together\n\t// or after displaying the help screen and prevent further execution in the CLI's promise chain.\n\thelpExitCode: undefined,\n\n\t// The name of the program used by the help screen to display the command's usage.\n\t// Defaults to \"program\".\n\tname: 'program',\n\n\t// An object of option formats to option descriptors or an array of sorted group names and\n\t// objects of option formats to option descriptors.\n\toptions: {\n\t\t//\n\t},\n\n\t// The title for the top-level (or \"Global\") context. This title is displayed on the help screen\n\t// when displaying the list of options.\n\ttitle: 'Global',\n\n\t// When set, it will automatically wire up the `-v, --version` option. Upon calling with your\n\t// program with `--version`, it will display the version and exit with a success (zero) exit\n\t// code.\n\tversion: null\n});\n```\n\n#### `exec(args)`\n\nParses the command line args and executes a command, if found.\n\n* `args` : `Array\u003cString\u003e` (optional)\n\n  An array of arguments. Each argument is expected to be a string.\n\n  Defaults to `process.argv.slice(2)`.\n\nReturns a `Promise` that resolves an `Arguments` object. This object will contain the parsed options\nin `argv` and arguments in `_`.\n\n##### Example\n\n```js\ncli.exec()\n\t.then(({ argv, _ }) =\u003e {\n\t\tconsole.log('options:', argv);\n\t\tconsole.log('args:', _);\n\t});\n```\n\n### class `Context`\n\nBase class for `CLI` and `Command` classes.\n\nExtends [`HookEmitter`](https://www.npmjs.com/package/hook-emitter).\n\n#### `argument(arg)`\n\nAdds an argument to a `CLI` or `Command`.\n\n* `arg` : `Argument`, `Object`, or `String`.\n\n  An argument descriptor. Either an `Argument` instance or an `Object` to pass into a `Argument`\n  constructor.\n\n  An argument requires a `name`.\n\nReturns a reference to the `CLI` or `Command`.\n\n##### Example\n\n```js\n// define a non-required argument \"foo\"\ncli.argument('foo');\n\n// define a non-required argument \"wiz\"\ncli.argument('[wiz]');\n\n// define a required argument \"pow\"\ncli.argument('\u003cpow\u003e');\n\ncli.argument({\n\tname: 'bar',\n\ttype: 'int'\n});\n\ncli.argument(new Argument('baz'));\n```\n\n#### `command(cmd, opts)`\n\nAdds a command to a `CLI` or `Command`.\n\n\u003e TODO\n\n#### `option(optOrFormat, group, params)`\n\nAdds an option or group of options to a `CLI` or `Command`.\n\n\u003e TODO\n\n## Who Uses cli-kit?\n\n * [Axway](https://www.axway.com)\n\n## License\n\nMIT\n\n[npm-image]: https://img.shields.io/npm/v/cli-kit.svg\n[npm-url]: https://npmjs.org/package/cli-kit\n[downloads-image]: https://img.shields.io/npm/dm/cli-kit.svg\n[downloads-url]: https://npmjs.org/package/cli-kit\n[build-image]: https://github.com/cb1kenobi/cli-kit/actions/workflows/build.yml/badge.svg\n[build-url]: https://github.com/cb1kenobi/cli-kit/actions/workflows/build.yml\n[david-image]: https://img.shields.io/david/cb1kenobi/cli-kit.svg\n[david-url]: https://david-dm.org/cb1kenobi/cli-kit\n[david-dev-image]: https://img.shields.io/david/dev/cb1kenobi/cli-kit.svg\n[david-dev-url]: https://david-dm.org/cb1kenobi/cli-kit#info=devDependencies\n[xterm]: https://xtermjs.org/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappcelerator%2Fcli-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappcelerator%2Fcli-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappcelerator%2Fcli-kit/lists"}