cli-argv-util

cli-argv-util

Simple utility to parse command line parameters and flags (arguments vector)

cli-argv-util is called from your bin/cli.js file in order to read user supplied information on the command line and return the flags and parameters in an easy-to-use structure.

A) Setup

Install package for node:

$ npm install cli-argv-util

B) Usage

Place the following code in your bin/cli.js file

import { cliArgvUtil } from 'cli-argv-util';

const validFlags = ['cd', 'find', 'no-summary'];
const cli =        cliArgvUtil.parse(validFlags);
if (cli.invalidFlag)
   throw new Error(cli.invalidFlagMsg);
if (cli.flagOn.find)
   console.info('You set the --find CLI flag to:', cli.flagMap.find);
if (cli.flagOn.noSummary)
   console.info('You enabled the --no-summary CLI option.');
console.info('You supplied', cli.params.length , 'CLI parameter(s).');

For a real world example, see: copy-file.ts

If your CLI tool is named my-program and a user runs it like:

$ my-program about.html --cd=src --no-summary 'Hello World' 777

the resulting cli object will be:

{
   flagMap: {
      cd: 'src',
      },
   flagMapRaw: {
      cd: 'src',
      },
   flagOn: {
      cd:        true,
      find:      false,
      noSummary: true,
      },
   invalidFlag:    null,
   invalidFlagMsg: null,
   params:         ['about.html', 'Hello World', '777'],
}

Single quotes in commands are normalized so they work cross-platform and avoid the errors often encountered on Microsoft Windows.

CLI flag values support escaped charcters and macros.
For documentation, see: https://github.com/center-key/replacer-util

C) Results

The cliArgvUtil.parse() returns an object of type Result:

export type StringFlagMap =  { [flag: string]: string | undefined };
export type BooleanFlagMap = { [flag: string]: boolean };
export type Result = {
   flagMap:        StringFlagMap,   //map of unescaped flag values for each user supplied flag
   flagMapRaw:     StringFlagMap,   //map of flag values for each user supplied flag
   flagOn:         BooleanFlagMap,  //map of the enabled status for all valid flags
   invalidFlag:    string | null,   //name of the first invalid flag
   invalidFlagMsg: string | null,   //error message for the invalid flag
   params:         string[],        //array of parameter values supplied by the user
   };

See the TypeScript Declarations at the top of cli-argv-util.ts for documentation.

---

MIT License

See the runScriptsConfig section of package.json for a clean way to organize build tasks:

• add-dist-header —  Prepend a one-line banner comment (with license notice) to distribution files
• copy-file-util —  Copy or rename a file with optional package version number
• copy-folder-util —  Recursively copy files from one folder to another folder
• recursive-exec —  Run a command on each file in a folder and its subfolders
• replacer-util —  Find and replace strings or template outputs in text files
• rev-web-assets —  Revision web asset filenames with cache busting content hash fingerprints
• run-scripts-util —  Organize npm package.json scripts into groups of easy-to-manage commands
• w3c-html-validator —  Check the markup validity of HTML files using the W3C validator