cli-argv-util

cli-argv-util

<img src=https://centerkey.com/graphics/center-key-logo.svg align=right width=200 alt=logo>

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 Error(cli.invalidFlagMsg);
if (cli.flagOn.find)
   console.log('You set the --find CLI flag to:', cli.flagMap.find);
if (cli.flagOn.noSummary)
   console.log('You enabled the --no-summary CLI option.');
console.log('You supplied', cli.params.length , 'CLI parameter(s).');

For a real world example, see: cli.js

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',
      },
   flagOn: {
      cd:        true,
      find:      false,
      noSummary: true,
      },
   invalidFlag:    null,
   invalidFlagMsg: null,
   params:         ['about.html', 'Hello World', '777'],
}

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

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 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.

---

CLI Build Tools for package.json

• 🎋 add-dist-header:  Prepend a one-line banner comment (with license notice) to distribution files
• 📄 cli-argv-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 scripts into named groups of easy to manage commands
• 🚦 w3c-html-validator:  Check the markup validity of HTML files using the W3C validator

Feel free to submit questions at:
github.com/center-key/cli-argv-util/issues

MIT License