getopts

What is getopts?

The getopts npm package is a lightweight and fast option parser for Node.js. It is used to parse command-line options and arguments in a simple and efficient manner.

What are getopts's main functionalities?

Basic Option Parsing

This feature allows you to parse command-line options and arguments. The code sample demonstrates how to use getopts to parse the command-line arguments passed to a Node.js script.

const getopts = require('getopts');
const options = getopts(process.argv.slice(2));
console.log(options);

Default Values

This feature allows you to set default values for options. The code sample shows how to provide default values for the 'name' and 'age' options.

const getopts = require('getopts');
const options = getopts(process.argv.slice(2), {
  default: {
    name: 'defaultName',
    age: 25
  }
});
console.log(options);

Aliases

This feature allows you to define aliases for options. The code sample demonstrates how to set up aliases for the 'name' and 'age' options.

const getopts = require('getopts');
const options = getopts(process.argv.slice(2), {
  alias: {
    n: 'name',
    a: 'age'
  }
});
console.log(options);

Boolean Options

This feature allows you to specify which options should be treated as boolean. The code sample shows how to define 'verbose' and 'debug' as boolean options.

const getopts = require('getopts');
const options = getopts(process.argv.slice(2), {
  boolean: ['verbose', 'debug']
});
console.log(options);

Unknown Option Handling

This feature allows you to handle unknown options. The code sample demonstrates how to log an error message for unknown options and prevent them from being included in the parsed options.

const getopts = require('getopts');
const options = getopts(process.argv.slice(2), {
  unknown: (option) => {
    console.error(`Unknown option: ${option}`);
    return false;
  }
});
console.log(options);

Other packages similar to getopts

minimist

Minimist is a popular option parser for Node.js that is similar to getopts. It provides a simple way to parse command-line arguments and supports features like default values, aliases, and boolean options. Compared to getopts, minimist is more widely used and has a larger community.

yargs

Yargs is a powerful option parser for Node.js that offers a rich set of features for building command-line tools. It supports advanced features like command handling, middleware, and interactive prompts. Yargs is more feature-rich compared to getopts, making it suitable for more complex CLI applications.

commander

Commander is a comprehensive option parser and command-line interface (CLI) framework for Node.js. It provides a robust set of features for defining commands, options, and arguments. Commander is more feature-complete compared to getopts and is ideal for building complex CLI applications with multiple commands.

README

Getopts

Getopts is a Node.js CLI options parser. It's designed according to the Utility Conventions so that your programs behave like typical UNIX utilities effortlessly — without sacrificing developer experience.

Need for speed? Getopts is optimized for runtime performance and runs 10 to 20 times faster than alternatives according to our benchmarks.

Installation

npm i getopts

Usage

Use getopts to parse the arguments passed into your program from the command line.

$ example/demo --super=sonic -xU9000 -- game over

const getopts = require("getopts")

const options = getopts(process.argv.slice(2), {
  alias: {
    s: "super",
    U: "ultra"
  },
  default: {
    turbo: true
  }
})

Getopts expects an array of arguments and options object (optional) and returns an object where you can look up the argument keys and their values.

{
  _: ["game", "over"],
  x: true,
  s: "sonic",
  U: "9000",
  super: "sonic",
  ultra: "9000",
  turbo: true
}

API

getopts(argv, options)

argv

An array of arguments to parse. See process.argv.

Arguments that begin with one or two dashes are called options or flags. Options may have one or more aliases. The underscore key stores operands. Operands include non-options, the single dash - and all the arguments after --.

options.alias

An object of option aliases. An alias can be a string or an array of strings.

getopts(["-U"], {
  alias: {
    U: ["u", "ultra"]
  }
}) //=> { _:[], u:true, U:true, ultra:true }

options.boolean

An array of options that should be parsed as booleans. In the example, by indicating U to be a boolean option, 1 is parsed as an operand.

getopts(["-U", 1], {
  boolean: ["U"]
}) //=> { _:[1], U:true }

options.default

An object of default values for missing options.

getopts(["-U"], {
  default: {
    turbo: true
  }
}) //=> { _:[], U:true, turbo:true }

options.unknown

A function that runs for every unknown option. Return false to dismiss the option.

getopts(["-abc"], {
  unknown: option => "a" === option
}) // => { _:[], a:true }

License

Getopts is MIT licensed. See LICENSE.