{"_id":"@isaacs/cli-env-config","_rev":"290318","name":"@isaacs/cli-env-config","description":"an options parser for environment variable configuration","dist-tags":{"latest":"1.0.2"},"maintainers":[{"name":"isaacs","email":""}],"time":{"modified":"2023-10-06T06:29:55.000Z","created":"2022-05-02T15:23:19.469Z","1.0.2":"2022-06-19T22:43:28.698Z","1.0.1":"2022-05-03T18:35:10.537Z","1.0.0":"2022-05-02T15:23:19.469Z"},"users":{},"author":{"name":"Isaac Z. Schlueter","email":"i@izs.me","url":"https://izs.me"},"repository":{"type":"git","url":"git+https://github.com/isaacs/cli-env-config.git"},"versions":{"1.0.2":{"name":"@isaacs/cli-env-config","version":"1.0.2","main":"lib/index.js","description":"an options parser for environment variable configuration","repository":{"type":"git","url":"git+https://github.com/isaacs/cli-env-config.git"},"author":{"name":"Isaac Z. Schlueter","email":"i@izs.me","url":"https://izs.me"},"license":"ISC","scripts":{"prepare":"tsc","format":"prettier --write . --loglevel warn","test":"c8 tap test/*.ts","snap":"c8 tap test/*.ts","pretest":"tsc","presnap":"tsc","preversion":"npm test","postversion":"npm publish","prepublishOnly":"git push origin --follow-tags"},"prettier":{"semi":false,"printWidth":70,"tabWidth":2,"useTabs":false,"singleQuote":true,"jsxSingleQuote":false,"bracketSameLine":true,"arrowParens":"avoid","endOfLine":"lf"},"tap":{"coverage":false,"node-arg":["--loader","ts-node/esm"],"ts":false},"devDependencies":{"@types/node":"^17.0.31","@types/tap":"^15.0.6","c8":"^7.11.2","eslint-config-prettier":"^8.5.0","prettier":"^2.6.2","tap":"^16.0.1","ts-node":"^10.7.0","tslib":"^2.4.0","typescript":"^4.6.4"},"engines":{"node":">=12"},"types":"./lib/index.d.ts","gitHead":"9e753e55101295eef0153fd3a7c947f3ce459875","bugs":{"url":"https://github.com/isaacs/cli-env-config/issues"},"homepage":"https://github.com/isaacs/cli-env-config#readme","_id":"@isaacs/cli-env-config@1.0.2","_nodeVersion":"18.4.0","_npmVersion":"8.12.1","dist":{"shasum":"d983495f52c034c9ff4c2bd87bcbbd99a3237af2","size":8565,"noattachment":false,"key":"/@isaacs/cli-env-config/-/@isaacs/cli-env-config-1.0.2.tgz","tarball":"http://name.csiicloud.com:7001/@isaacs/cli-env-config/download/@isaacs/cli-env-config-1.0.2.tgz"},"_npmUser":{"name":"isaacs","email":"i@izs.me"},"directories":{},"maintainers":[{"name":"isaacs","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/cli-env-config_1.0.2_1655678608475_0.070791348158731"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2022-06-19T22:43:32.616Z","publish_time":1655678608698,"_cnpm_publish_time":1655678608698},"1.0.1":{"name":"@isaacs/cli-env-config","version":"1.0.1","main":"lib/index.js","description":"an options parser for environment variable configuration","repository":{"type":"git","url":"git+https://github.com/isaacs/cli-env-config.git"},"author":{"name":"Isaac Z. Schlueter","email":"i@izs.me","url":"https://izs.me"},"license":"ISC","scripts":{"prepare":"tsc","format":"prettier --write . --loglevel warn","test":"c8 tap test/*.ts","snap":"c8 tap test/*.ts","pretest":"tsc","presnap":"tsc","preversion":"npm test","postversion":"npm publish","prepublishOnly":"git push origin --follow-tags"},"prettier":{"semi":false,"printWidth":70,"tabWidth":2,"useTabs":false,"singleQuote":true,"jsxSingleQuote":false,"bracketSameLine":true,"arrowParens":"avoid","endOfLine":"lf"},"tap":{"coverage":false,"node-arg":["--loader","ts-node/esm"],"ts":false},"devDependencies":{"@types/node":"^17.0.31","@types/tap":"^15.0.6","c8":"^7.11.2","eslint-config-prettier":"^8.5.0","prettier":"^2.6.2","tap":"^16.0.1","ts-node":"^10.7.0","tslib":"^2.4.0","typescript":"^4.6.4"},"engines":{"node":">=12"},"types":"./lib/index.d.ts","gitHead":"da76b1a74cde1ed79e8de38623723fabb9c07833","bugs":{"url":"https://github.com/isaacs/cli-env-config/issues"},"homepage":"https://github.com/isaacs/cli-env-config#readme","_id":"@isaacs/cli-env-config@1.0.1","_nodeVersion":"18.0.0","_npmVersion":"8.6.0","dist":{"shasum":"9b9a3074654772533fa8034c577580c9567df95b","size":8253,"noattachment":false,"key":"/@isaacs/cli-env-config/-/@isaacs/cli-env-config-1.0.1.tgz","tarball":"http://name.csiicloud.com:7001/@isaacs/cli-env-config/download/@isaacs/cli-env-config-1.0.1.tgz"},"_npmUser":{"name":"isaacs","email":"i@izs.me"},"directories":{},"maintainers":[{"name":"isaacs","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/cli-env-config_1.0.1_1651602910296_0.7677702464672598"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2022-05-03T18:50:36.200Z","publish_time":1651602910537,"_cnpm_publish_time":1651602910537},"1.0.0":{"name":"@isaacs/cli-env-config","version":"1.0.0","main":"lib/index.js","description":"an options parser for environment variable configuration","repository":{"type":"git","url":"git+https://github.com/isaacs/cli-env-config.git"},"author":{"name":"Isaac Z. Schlueter","email":"i@izs.me","url":"https://izs.me"},"license":"ISC","scripts":{"prepare":"tsc","format":"prettier --write . --loglevel warn","test":"c8 tap test/*.ts","snap":"c8 tap test/*.ts","pretest":"tsc","presnap":"tsc","preversion":"npm test","postversion":"npm publish","prepublishOnly":"git push origin --follow-tags"},"prettier":{"semi":false,"printWidth":70,"tabWidth":2,"useTabs":false,"singleQuote":true,"jsxSingleQuote":false,"bracketSameLine":true,"arrowParens":"avoid","endOfLine":"lf"},"tap":{"coverage":false,"node-arg":["--loader","ts-node/esm"],"ts":false},"devDependencies":{"@types/node":"^17.0.31","@types/tap":"^15.0.6","c8":"^7.11.2","eslint-config-prettier":"^8.5.0","prettier":"^2.6.2","tap":"^16.0.1","ts-node":"^10.7.0","tslib":"^2.4.0","typescript":"^4.6.4"},"engines":{"node":">=12"},"types":"./lib/index.d.ts","gitHead":"53dea13a627ad13889819b0b8e2ffb0516df0174","bugs":{"url":"https://github.com/isaacs/cli-env-config/issues"},"homepage":"https://github.com/isaacs/cli-env-config#readme","_id":"@isaacs/cli-env-config@1.0.0","_nodeVersion":"18.0.0","_npmVersion":"8.6.0","dist":{"shasum":"8e29a5bd90f0aee0534c7b85eab71ace364a4b27","size":8121,"noattachment":false,"key":"/@isaacs/cli-env-config/-/@isaacs/cli-env-config-1.0.0.tgz","tarball":"http://name.csiicloud.com:7001/@isaacs/cli-env-config/download/@isaacs/cli-env-config-1.0.0.tgz"},"_npmUser":{"name":"isaacs","email":"i@izs.me"},"directories":{},"maintainers":[{"name":"isaacs","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/cli-env-config_1.0.0_1651504999284_0.9687511661081019"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2022-05-02T15:46:54.798Z","publish_time":1651504999469,"_cnpm_publish_time":1651504999469}},"readme":"# @isaacs/cli-env-config\n\nAn options parser for environment variable configuration.\n\nAll options correspond to environment variables. So, if you\ndefine `foo-bar`, then you can use `--foo-bar=value` on the\ncommand line, or set `MY_APP_FOO_BAR=value` in the environment,\nand get `fooBar: 'value'` in the options object.\n\nCLI options override the environment. Whatever the settings are,\nthey are put into the environment, so your cli app can consume\nthem from there, or from the `options` object it creates.\n\nOptions like `--key=value` and `--key value` are supported for\nvalue-taking keys. Switches are booleans, so `--key` sets them\ntrue. Counts are switches that return the number of times\nthey're set. Multivars are options that can be set multiple\ntimes.\n\nCounts are numbers. Switches are booleans. Options are stringly\ntyped. Multivars are arrays of strings (zero-length\nwhen not set, so they're always an array).\n\nIn the environment, multivars are `\\n\\n`-delimited. Switches are\nset/read in the environment as `'1'` for true and `'0'` for\nfalse. Counts are set/read in the environment as decimal\ninteger strings.\n\nShort options are supported POSIX-style, so if `-b` is a\nshorthand for `--bar` switch, and `-f` is shorthand for the\n`--foo` option, then `-bfasdf` and `-bf asdf` are both equivalent\nto `--bar --foo=asfd`.\n\nThis library does not print your usage banner for you, sorry.\n\n## INSTALL\n\n```bash\nnpm install cli-env-config\n```\n\n## USAGE\n\nBig illustrative example with all the fixins:\n\n```js\nconst { cliEnvConfig } = require('cli-env-config')\n\n// create a config parser based on our app's needs\nconst parse = cliEnvConfig({\n  // all envs are prefixed with 'MY_APP_...'\n  prefix: 'MY_APP'\n\n  // these take a value, stringly typed, last one wins\n  options: ['api', 'foo'],\n\n  // these are on or off.  '1' in env for true, '0' for false\n  // string name, or [name, short flag].\n  //\n  // the camelcase name here is what ends up in the env.  the cli\n  // flag is the css-case form, so --camel-case.\n  // the env is prefixed with ${prefix}, and upper-snake case, so\n  // MY_APP_CAMEL_CASE\n  switches: ['camelCase', ['debug', 'd'], ['help', 'h']],\n  // switch inverts make a switch be turned off\n  // they don't end up on the config object\n  //\n  // And because I can never remember whether these sorts of\n  // things need to be camel or css case, either works, but it's\n  // always css-case in the cli, and always camelCase in the\n  // config obj, obviously.\n  switchInverts: [['no-debug', 'debug', 'D']],\n\n  // these are set to the number of times they're specified\n  counts: [['verbose', 'v']],\n  // countDecrements make a counter go down\n  countInverts: [['quiet', 'verbose', 'q']],\n\n  // these return an array of all options, \\n\\n-delimited in env\n  multivars: [['header', 'H']],\n\n  // options:\n  // true: leave unknown options in the argv array\n  // false (default): throw an error on any unknown --option args\n  allowUnknown: true,\n})\n\n// argv is what remains\n// options is the resolved values\nconst {config, argv} = parse(process.argv.slice(2))\n\n// then you can use the config object and the argv to do\n// whatever, or just code against the process.env values.\n```\n\nMore minimal/realistic example:\n\n```js\n// create the parser\nimport { cliEnvConfig } from '@isaacs/cli-env-config'\nconst parseArgv = cliEnvConfig({\n  prefix: 'MY_APP',\n  options: [['apiUrl', 'a'], ['webUrl', 'w'], ['key', 'k'], 'authType'],\n  switches: [\n    ['debug', 'd'],\n    ['help', 'h'],\n  ],\n  switchInverts: [['noDebug', 'debug', 'D']],\n})\n\n\nconst main = () => {\n  // use it\n  const {argv, config} = parseArgv(process.argv.slice(2))\n  if (config.help) {\n    return console.log('Usage: myapp <thing|other> [options]')\n  }\n  const cmd = argv.shift()\n  switch (cmd) {\n    case 'thing': return doThing(argv, config)\n    case 'other': return doOther(argv, config)\n    default: throw `Unknown command: ${cmd}`\n  }\n}\nmain()\n```\n\n## API\n\n### `cliEnvConfig(configDefs: ConfigDef) => ConfigParseFunction`\n\nReturn a function that parses an argv array and returns the\nconfig object and sets environment variables.\n\n### `ConfigDef` type\n\n* `prefix` The name of your app.  Required.\n* `options`: Array of option name strings or `[name, shortFlag]`\n  tuples.  These keys must take a value.\n* `switches`: Array of switch name strings or `[name, shortFlag]`\n  tuples.  These keys must not take a value, they are true if\n  set.\n* `switchInverts`: Array of `[name, target]` or `[name, target,\n  shortFlag]` tuples.  The `target` is a `switch` that this\n  switch sets to `false`.\n* `counts`: Array of counter name strings or `[name, shortFlag]`\n  tuples.  These may be set multiple times, each time increments\n  the counter.\n* `countInverts`: Array of `[name, target]` or `[name, target,\n  shortFlag]` tuples.  The `target` is a `count` that this switch\n  decrements.\n* `multivars`: Array of multivar name strings or `[name,\n  shortFlag]` tuples.  These take a value, and may be set\n  multiple times.  The resulting value is an array of all values\n  provided.\n* `allowUnknown`: Boolean, default false.  Treats unrecognized\n  `-flag` and `--option` arguments as positionals, including them\n  in the returned `argv`\n* `env`: The environment object to use, defaults to `process.env`\n\n### `ConfigParseFunction`\n\nReturned by `cliEnvConfig`.\n\nParses an `argv` array of strings, returning a `config` object\nand `argv` of remaining positional arguments.\n\nStops parsing when `--` is encountered, and includes the `--` in\nthe returned `argv`.\n\nSets all environment variables appropriately in the `env` object\nprovided in the `ConfigDef` to `cliEnvConfig()`.\n\nThrows if the argv cannot be parsed correctly.  (For example, if\na value is provided to a `switch` type argument, or no value is\nprovided to an `option` type argument.)\n\n### Option Types\n\n* `option` Value must be provided.  Uses the last value\n  specified.  Stored in the environment as the last string value.\n  Set to an empty string with `--name=`.\n* `switch` Value must not be provided.  Boolean, set true by\n  setting the option, or set false with a `switchInvert`\n  argument.  Stored in the environment as `'1'` for true and\n  `'0'` for false.\n* `count` Value must not be provided, may be specified multiple\n  times.  Integer, incremented by setting the option, or\n  decremented by a `countInvert` argument.  Set in the\n  environment as a decimal string.\n* `multivar` Value must be provided, may be specified multiple\n  times.  Array of all string values provided.  Set in the\n  environment as a `\\n\\n`-delimited list of all values provided.\n\n## WHY\n\nThe absolutely _last_ thing that the npm registry needs in 2022\nis yet another cli options parser, it's true.\n\nBut I found that I kept having to re-implement the same bit of\nfunctionality, where I'd check the env, then have the cli parser\nknow to set this flag to that environment variable, use the env\nas a default but still override it when it's explicitly set, and\nso on. And then does the code use the env, or the an explicit\noption? Always a pile of decisions to be made, none of them\nentirely obvious. Sometimes I'd add a new config key, but forget\nto default it to the environment, so things would get out of sync.\n\nI thought it might be easier to just have one way to do that,\ndefine a bunch of switches and options and booleans, and then get\nconfiguration and environment variable handling all included in\none consistent thing, so the env is always set, the config always\nmatches it, and the user can set it either way to get the same\neffect.\n\nAlso, all the other cli options definition systems were really\nverbose, even [jackspeak](http://npm.im/jackspeak) which I\nspecifically designed to be as terse as I could make it. I\nthought it might be nice to see how minimal I could get the\ninterface.\n","_attachments":{},"homepage":"https://github.com/isaacs/cli-env-config#readme","bugs":{"url":"https://github.com/isaacs/cli-env-config/issues"},"license":"ISC"}