{"id":21414882,"url":"https://github.com/magic/cli","last_synced_at":"2025-07-14T04:31:16.107Z","repository":{"id":54292438,"uuid":"183785438","full_name":"magic/cli","owner":"magic","description":"@magic cli wrapper. declarative command line interfaces for any nodejs script.","archived":false,"fork":false,"pushed_at":"2023-04-04T16:43:01.000Z","size":1519,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-12T00:51:30.668Z","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":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magic.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-27T14:47:50.000Z","updated_at":"2025-06-09T19:03:22.000Z","dependencies_parsed_at":"2024-06-19T02:45:54.079Z","dependency_job_id":"a2e6d4b7-0c82-4993-9ec4-205486af5e54","html_url":"https://github.com/magic/cli","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/magic/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magic%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magic%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magic%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magic%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magic","download_url":"https://codeload.github.com/magic/cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magic%2Fcli/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265017897,"owners_count":23698580,"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":[],"created_at":"2024-11-22T18:34:23.830Z","updated_at":"2025-07-14T04:31:15.698Z","avatar_url":"https://github.com/magic.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## @magic/cli\n\ndeclarative cli sanitization and execution for [@magic](https://magic.github.io/cli)\n\nsanitizes cli flags from aliases to default names\n\nrewrites process.argv accordingly\n\nprovides autogenerated --help output (that can be customized)\n\nhandles commands and environment.\n\n### v0.0.11+:\n\necmascript modules only. no commonjs support.\n\n[html-docs](https://magic.github.io/cli/)\n\n[![NPM version][npm-image]][npm-url]\n[![Linux Build Status][travis-image]][travis-url]\n[![Windows Build Status][appveyor-image]][appveyor-url]\n[![Coverage Status][coveralls-image]][coveralls-url]\n[![Greenkeeper badge][greenkeeper-image]][greenkeeper-url]\n[![Known Vulnerabilities][snyk-image]][snyk-url]\n\n[npm-image]: https://img.shields.io/npm/v/@magic/cli.svg\n[npm-url]: https://www.npmjs.com/package/@magic/cli\n[travis-image]: https://img.shields.io/travis/com/magic/cli.svg?branch=master\n[travis-url]: https://travis-ci.com/magic/cli\n[appveyor-image]: https://img.shields.io/appveyor/ci/magic/cli/master.svg\n[appveyor-url]: https://ci.appveyor.com/project/magic/cli/branch/master\n[coveralls-image]: https://coveralls.io/repos/github/magic/cli/badge.svg\n[coveralls-url]: https://coveralls.io/github/magic/cli\n[greenkeeper-image]: https://badges.greenkeeper.io/magic/cli.svg\n[greenkeeper-url]: https://badges.greenkeeper.io/magic/cli.svg\n[snyk-image]: https://snyk.io/test/github/magic/cli/badge.svg\n[snyk-url]: https://snyk.io/test/github/magic/cli\n\n- [dependencies](#dependencies)\n- [install](#install)\n- [caveats](#caveats)\n- [usage](#usage)\n- [argv](#argv)\n- [commands](#commands)\n- [help](#help)\n- [config](#configuration)\n- [pure](#config-pure)\n- [append / prepend](#prepend-append)\n- [default](#default)\n\n### \u003ca name=\"dependencies\"\u003e\u003c/a\u003edependencies:\n\n- [@magic/log](https://github.com/magic/log): console.log wrapper with loglevels\n- [@magic/types](https://github.com/magic/types): type checking library\n- [@magic/types](https://github.com/magic/cases): case checking library (CamelCase, snake_case, kebab-case)\n\n@magic/log, @magic/cases and @magic/types have no dependencies.\n\n### \u003ca name=\"install\"\u003e\u003c/a\u003einstall\n\nbe in a node ecmascript module project.\n\n```bash\nnpm i --save-dev --save-exact @magic/cli\n```\n\n### \u003ca name=\"caveats\"\u003e\u003c/a\u003ecaveats\n\nthere are some quirks that need some careful consideration when designing a cli api\ndepending on your requirements, these caveats should seldomly apply.\n\n##### last argument\n\nif your last argument does not have a corresponding flag,\nit will still be assigned to the last flag prior to it.\n\n##### command name overload\n\nif one of your options gets an argument that is equal to a command,\nthis command will be executed\n\n##### flag name overload\n\ncli arguments that start with a - will always be treated as flags, not values.\n\n_those issues might get addressed in the future._\n\n### \u003ca name=\"usage\"\u003e\u003c/a\u003eUsage\n\nfirst, define the cli file\n\n```javascript\n// ./bin.mjs\nimport { cli } from '@magic/cli'\n\nconst res = cli({\n  commands: [['cmd1', 'cmd1alias'], 'cmd2'],\n  options: [\n    ['--flag1', '-f1'],\n    ['--flag2', '-f2'],\n  ],\n  default: {\n    '--default-key': 'default-value',\n  },\n  required: ['--default-key'],\n  single: ['--default-key'],\n  env: [[['--production', '--prod', '--p', '-p'], 'NODE_ENV', 'production']],\n  pure: true, // do neither change process.argv nor process.env\n  pureArgv: true, // do not change process.argv\n  pureEnv: true, // do not change process.env\n})\n\nconsole.log(res)\n```\n\n### \u003ca name=\"argv\"\u003e\u003c/a\u003eoptions / argv\n\nargv mappings handle options and option aliases\n\nusing the cli file above\n\n```bash\n./bin.mjs -f1 arg1 arg2 -f2\n```\n\nresulting process.argv:\n\n```javascript\nprocess.argv = [\n  '/path/to/bin/node',\n  '/path/to/bin.mjs',\n  'cmd1',\n  '--flag1'\n  'arg1',\n  'arg2',\n  '--flag2',\n]\n```\n\nlogged javascript object\n\n```javascript\n{\n  argv: { '--flag1': ['arg1', arg2], '--flag2': [] },\n  args: { flag1: ['arg1', 'arg2'], flag2: [] },\n  // ... other fields\n}\n```\n\n### \u003ca name=\"commands\"\u003e\u003ca\u003ecommands\n\ncli commands will be handled too.\n\n```javascript\n// call\n./bin.js cmd1\n\n// results:\n{\n  commands: { cmd1: true },\n  // ... other fields\n}\n```\n\n### \u003ca name=\"help\"\u003e\u003c/a\u003ehelp output\n\n@magic/cli will parse your configuration and create a help text based on it.\n\n#### \u003ca name=\"help-simple\"\u003e\u003c/a\u003esimple help message\n\n```javascript\n// ./bin.mjs\n\nimport cli from '@magic/cli'\n\nconst args = {\n  commands: [['magic', 'm']],\n  options: [['--spell', '-s']],\n  env: [[['dev', 'development'], 'NODE_ENV', 'development']],\n  help: 'custom help text',\n}\n\nconst argv = cli(args)\n```\n\nthen run ./bin.mjs without arguments\n\n```bash\n./bin.mjs\n\n// help output\n`\n@magic/cli wrapped cli.\n\ncustom help text\n\ncli commands\nmagic - aliases: [\"m\"]\n\n\npossible command line flags:\n--spell - aliases: [\"-s\"]\n\nenvironment switches:\ndev: set NODE_ENV to development - aliases [\"development\"]\n`\n```\n\n#### \u003ca name=\"help-detailed\"\u003e\u003c/a\u003edetailed help message\n\nthe help property will accept an object which maps to the args object\n\n```javascript\nimport cli from '@magic/cli'\n\nconst args = {\n  commands: [['magic', 'm']],\n  options: [['--spell', '-s']],\n  env: [[['dev', 'development'], 'NODE_ENV', 'development']],\n  prepend: 'prepend',\n  append: 'append',\n  help: {\n    name: 'cli name',\n    text: 'custom help text',\n    commands: {\n      magic: 'magic info help text',\n    },\n    options: {\n      '--spell': 'cast a simple spell',\n    },\n    env: ['dev', 'set environment to development'],\n  },\n}\n\nconst argv = cli(args)\n\n// running\n./bin.js\n// without arguments\n\n// help output\n`\ncli name\n\ncustom help text\n\ncommands:\nmagic - aliases: [\"m\"]\n\nflags:\n--spell - aliases: [\"-s\"]\n\nenvironment switches:\ndev: set process.NODE_ENV to development - aliases [\"development\"]\n`\n```\n\n### \u003ca name=\"clean\"\u003e\u003c/a\u003eclean\n\nsome cli arguments will be expected to return a string instead of a list of arguments.\n\nthis can be achieved using the single array\n\n```javascript\nconst args = {\n  options: [['--single', '-s']],\n  single: ['--single'],\n}\n\nconst res = cli(args)\n\nconsole.log(res)\n```\n\n### \u003ca name=\"required\"\u003e\u003c/a\u003erequired\n\nsome cli arguments will be required.\n\nthis can be achieved using the required array.\n\nif a required field is missing, a error message and the help will be shown.\n\n```javascript\nconst args = {\n  options: [['--required', '-r']],\n  required: ['--required'],\n}\n\nconst res = cli(args)\n\nconsole.log(res)\n```\n\n### \u003ca name=\"config\"\u003e\u003c/a\u003econfiguration\n\nthere are some configuration parameters that can be passed to the cli function\n\n#### \u003ca name=\"config-pure\"\u003e\u003c/a\u003epure\n\n```javascript\nconst args = {\n  pure: false, // set to true to prevent changes to process.argv and process.env\n  pureEnv: false, // set to true to prevent changes to process.env\n  pureArgv: false, // set to true to prevent changes to process.argv\n}\n\ncli(args)\n```\n\n### \u003ca name=\"prepend-append\"\u003e\u003c/a\u003eprepend/append\n\nprocess.argv values can be prepended and appended\n\n```javascript\nimport cli from '@magic/cli'\n\nconst args = {\n  prepend: ['prepended']\n  append: ['appended']\n}\n\ncli(args)\n```\n\n#### \u003ca name=\"default\"\u003e\u003c/a\u003edefault\n\nuse this to set default process.argv key: value pairs that should be set if they are not\n\n```javascript\nimport cli from '@magic/cli'\n\nconst args = {\n  options: [\n    ['--default-key'],\n  ],\n  default: {\n    '--default-key': 'default-value',\n  },\n}\n\nconst argv = cli(args)\n\n// returns\n{\n  argv: {\n    '--default-key': 'default-value',\n  },\n}\n```\n\n### Changelog\n\n##### 0.0.1\n\nfirst release\n\n##### 0.0.3\n\ncli's should now correctly process.exit(1) on error of the spawned process.\n\n##### 0.0.4\n\nconsole help output now aligns nicely\n\n##### 0.0.5\n\nnode 12.4.0 does not have --experimental-node-modules fladg.\n\n##### 0.0.6\n\nreadd --experimental-node-modules flag for 13.1.0+\n\n##### 0.0.7\n\nupdate dependencies\nbump node version\n\n##### 0.0.8\n\nhelp is shown if cli has commands but none are given\n\n##### 0.0.9\n\nupdate dependencies\n\n##### 0.0.10\n\nupdate dependencies\n\n##### 0.0.11\n\n- parsed.args added. is copy of argv, but using camelCased keys without leading --.\n- no commonjs fallback, ecmascript modules all the way\n- parsed does not return aliases. env, argv, args, commands. thats it.\n\n##### 0.0.12\n\nadd @magic/cases dependency\n\n##### 0.0.13\n\nupdate deps\n\n##### 0.0.14\n\n--help works for cli scripts without commands too\n\n##### 0.0.15\n\ncli will always provide --help and -h flags to show help\n\n##### 0.0.16\n\n- args can be set to be single now, making them return a .join(' ')ed string instead of an array\n- args can be set to be required now, making the cli error and show the help if they are not.\n\n##### 0.0.17\n\nrequired args can now be an array. this allows '--a' or '--b' to be required.\nerrors if both are given.\n\n##### 0.0.18\n\n- the command `cli-name all` now automagically sets all available commands to true.\n- command keys will always be set to a boolean, return false if task is supposed to not be active.\n\n##### 0.0.19\n\nregression: calling cli that has commands without commands will show help again.\n\n##### 0.0.20\n\nregression: make commands only have keys for active commands again\n\n##### 0.0.21\n\nfinally get rid of the command regressions\n\n##### 0.0.22\n\n- add cli.prompt to get user input.\n- do not error if args.options is empty\n- exec and spawn now are separate functions corresponding to node builtins\n\n##### 0.0.23\n\n- cli.prompt: change call signature, remove PasswordStream\n\n##### 0.0.24\n\n- fix required node version\n- update dependencies\n\n##### 0.0.25\n\n- prompt now has a yesDefault option\n- prompt will add y/N or Y/n to the prompt message if it is missing\n\n##### 0.0.26\n\n- default help arguments are now output by default.\n\n##### 0.0.27\n\nnicer output for prompt messages\n\n##### 0.0.28\n\nbump required node version to 14.2.0\n\n##### 0.0.29\n\nupdate dependencies\n\n##### 0.0.30\n\n- update dependencies\n\n##### 0.0.31\n\n- bump required node version to 14.15.4\n- update dependencies\n\n##### 0.0.32\n\nupdate dependencies\n\n##### 0.0.33\n\nupdate dependencies\n\n##### 0.0.34\n\nupdate dependencies\n\n##### 0.0.35\n\n- parse now can get an opts object as third argument to overwrite child_process.exec options\n- help.argToHelp now errors if the first argument is not an array, before errors only got triggered by falsy arg.\n- exec now uses @magic/error for errors.\n- exec does not trim() the result.\n- findLongestString sorts by length and then alphabetically\n- export execFile\n- update dependencies\n\n##### 0.0.36\n\nupdate dependencies\n\n##### 0.0.37\n\nupdate dependencies\n\n##### 0.0.38\n\nupdate dependencies\n\n##### 0.0.39\n\n- update devdependencies\n- parse.argv does not error if args do not have a length\n\n##### 0.0.40\n\nupdate dependencies\n\n##### 0.0.41\n\nupdate dependencies\n\n##### 0.0.42\n\nupdate dependencies\n\n##### 0.0.43\n\nupdate dependencies\n\n##### 0.0.44\n\n- update dependencies\n- add colors to default arg output\n\n##### 0.0.45\n\n- help.example can be an array\n- update dependencies\n- cli.prompt - msg can be an array\n\n##### 0.0.46\n\n- cli.exec allows stderrToStdout redirect config option\n- update dependencies\n\n##### 0.0.47 - unreleased\n\n- ...\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagic%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagic%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagic%2Fcli/lists"}