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.

• Swift: Getopts is 10 to 1000 times faster than the alternatives. See benchmarks for details.
• Familiar: Getopts works similarly to other CLI parsers like mri, yargs and minimist.
• Predictable: Getopts is designed according to the Utility Syntax Guidelines.

Installation

Using npm or Yarn.

npm i getopts

Usage

Use Getopts to parse the arguments passed into your program.

$ example/demo --jet --mode=turbo -xfv12 -- game over

And create an object that you can use to lookup options and values.

const deepEqual = require("assert").deepEqual
const getopts = require("getopts")
const args = process.argv.slice(2)

deepEqual(getopts(args), {
  _: ["game", "over"],
  jet: true,
  mode: "turbo",
  x: true,
  f: true,
  v: "12"
})

Create option aliases.

deepEqual(
  getopts(args, {
    alias: {
      j: "jet",
      m: "mode",
      v: "viper"
    }
  }),
  {
    _: ["game", "over"],
    jet: true,
    j: true,
    mode: "turbo",
    m: "turbo",
    x: true,
    f: true,
    v: "12",
    viper: "12"
  }
)

Populate missing options with default values.

deepEqual(
  getopts(args, {
    default: {
      bolt: true,
      hyper: 9000
    }
  }),
  {
    _: ["game", "over"],
    jet: true,
    mode: "turbo",
    z: "12",
    bolt: true,
    hyper: 9000
  }
)

Identify options without an alias.

getopts(args, {
  alias: {
    j: "jet",
    m: "mode",
    v: "viper"
  },
  unknown(option) {
    throw new Error(`Unknown option: ${option}.`) // => Unknown option: x.
  }
})

API

getopts(args, options)

args

An array of arguments to parse. Use process.argv.slice(2).

options.alias

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

getopts(["-b"], {
  alias: {
    b: ["B", "boost"]
  }
}) //=> { _:[], b:true, B:true, boost:true }

options.default

An object of default values for missing options.

getopts(["-b"], {
  default: {
    super: 9000
  }
}) //=> { _:[], b:true, super:9000 }

options.unknown

A function we run for every option without an alias. Return false to dismiss the option.

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

License

Getopts is MIT licensed. See LICENSE.