clia

clia

Command line arguments parser and t3st example project.

usage

Example command line input:

node your-node-app hello -a -ab -d world

In your-node-app:

const clia = require('clia')

const conf = clia(process.argv.slice(2))

// test in your browser on: https://npm.runkit.com/clia
// const conf = clia('hello -a -ab -d world'.split(' '))

conf === {
  // arguments before any options
  plain: [ 'hello' ], 
  // options saved in opt (eg. --a -bd)
  opt: { a: true, b: true, d: true }, 
  // arguments after options are tagged with the last option (eg -d world, or --d world)
  // argument --key=value also saved in args, eg --d=world
  args: { d: [ 'world' ] }, 
  // the first value of each args property, so that you can use arg.prop instead of args.prop[0]
  arg: { d: 'world' }, 
}

edge cases

Spaces are trimmed from inputs.

Empty or non-string inputs are ignored.

Inputs that contain __proto__ or prototype are ignored. (To prevent prototype pollution.)

If there are any errors, there will be an errors property in the return value

Example invalid command line input:

node your-app.js valid --ok=yes prototype last-token

yields

{
    errors: [
        'One or more args were excluded from parsing. Reason: Not a string, string is empty or spaces only, string contains __proto__ or prototype.'
    ],
    arg: { ok: 'yes' },
    args: { ok: ['yes'] },
    opt: {},
    plain: ['valid', 'last-token']
}

It is recommended that you check for any input errors.

// in main.js/index.js
const conf = clia(process.argv.slice(2))

if(conf.errors){
    // graceful exit
    console.log('Could not parse command line input, errors:')
    console.log(conf.errors)
    require('process').exitCode(1)
    return
}

When -- is encountered, it is ignored. All subsequent inputs are treated as arguments even if they start with -.

Key-values with missing key or value are saved as-is: eg:

option --store= yields: { .. opt: { 'store=': true }

option --=pet yields: { .. opt: { '=pet': true }

alias

clia('run -o yaml --d=/usr/bin --fruit=mango'.split(' ')
                , ['output', 'directory', 'fruit'])

yields

{
    arg: {
        o: 'yaml', output: 'yaml',
        d: '/usr/bin', directory: '/usr/bin',
        fruit: 'mango'
    },
    args: {
        o: ['yaml'], output: ['yaml'],
        d: ['/usr/bin'], directory: ['/usr/bin'],
        // note key-value doesn't set option
        // even when kv/value matches alias 
        fruit: ['mango']
    },
    // note key-value doesn't set opt
    // even when kv/value is short option that has an alias
    opt: { o: true, output: true },
    plain: ['run']
}

Docs

All examples here

Dev/specs

Changelog

2020.8.11

• Set errors in optional property instead of throwing
• Save entire RHS of key-value = symbol
• Reject 'prototype' argument/options