opts.js is a Javascript helper library for command-line applications, for accepting and parsing command-line arguments,flags and options, and automatically generating a useful help message.

Introduction to Opts.js

Why choose opts.js over something bigger and better?

  • Small : Under 10kb, uncompressed.

  • Stable : Relatively unchanged since 2010. See changelog.

  • Standalone : No package manager necessary, no compiling needed. See src/opts.js.

  • Tested : Over 5 million downloads. See npm/opts.

Quick-Start example

The following example set up a custom "version" function, and opts in to the automatic help message. No pun intended.

opts/examples/example1.js

var opts = require('opts');

var options = [
  { short       : 'v'
  , long        : 'version'
  , description : 'Show version and exit'
  , callback    : function () { console.log('v1.0'); process.exit(1); }
  }
];

opts.parse(options, true);
console.log('Example 1');
process.exit(0);
node ./example1
Example 1
node ./example1 --help
Usage: node ./example1 [options]
Show this help message
   --help
Show version and exit
   -v, --version
node ./example1 -v
v1.0

See more examples below.

Installation

No NPM dependencies are required

To use opts.js, you do not need to use NPM or any package manager. It is written in plain-old Javascript, and can be downloaded and included in your Node.js project as-is. All of the examples use this approach.

cd /path/to/your/project
curl -o opts.js https://raw.githubusercontent.com/khtdr/opts/master/src/opts.js

Typescript and NPM packages for convenience

If you are using NPM in your project, you can install it using the name opts.

npm install opts

Basic usage and setup

To use, import the library and call opts.parse with your configurations. The various types of configurations are covered further down.

var opts = require('opts');
opts.parse(options, arguments, help);

or with the more modern syntax

import * as opts from 'opts';
opts.parse(options, arguments, help);

If you installed opts with NPM, the typescript definitions should automatically be available in your editor. Otherwise you can download the definition (.d.ts) file here.

API configurations

opts.parse(options, arguments, help)

Options are flag-arguments. Arguments are everything else. Consider the following hypothetical command for starting a server that listens on http://0.0.0.0:4000

node ./my-app start --host 0.0.0.0 -p 4000

In this example, the options are --host 0.0.0.0 and -p 4000. The argument is start. The arguments can be after, before, or among the options.

Options

options is an array of option objects. Each option in the array can have the following fields. None are required, but you should at least provide a short or long name.

let options = [
  { short       : 'l',
    long        : 'list',
    description : 'Show a list',
    value       : false, // default false
    required    : true, // default false
    callback    : function (value) { ... },
  }, // ... followed by more options
];

Arguments

arguments require less configuration. This is an optional argument to opts.parse:

let arguments = [
  { name     : 'script',
    required : true, // not required by default
    callback : function (value) { ... },
  }
];

Help auto-generator

Finally, you can add an automatically generated help message by passing a last parameter of true. This is also an optional argument to opts.parse.

opts.parse(options, true);
// or if you want more control, you can do:
/*
  options.push({
    long        : 'help',
    description : 'Show this help message',
    callback    : require('opts').help,
  }
  opts.parse(options);
*/

More examples

Showcase of features and options

opts/examples/example2.js

/**
 * More complex example.
 *
 * Run:
 *   node example2.js --help
 * and play with the options to see the behavior.
 *
 * This example shows different ways of using the library. It is deliberately
 * inconsistent. Choose the style that suits you best.
 */

var opts = require('opts')
  , host = 'localhost'; // default host value

var options = [
  { short       : 'v'
  , long        : 'version'
  , description : 'Show version and exit'
  , callback    : function () { console.log('v1.0'); process.exit(1); }
  },
  { short       : 'l'
  , long        : 'list'
  , description : 'List all files'
  },
  { short       : 'f'
  , long        : 'file'
  , description : 'Load a file'
  , value       : true
  , required    : true
  },
  { short       : 'd'
  , long        : 'debug'
  , description : 'Set a debug level'
  , value       : true
  },
  { short       : 'h'
  , long        : 'host'
  , description : 'The hostname to connect to'
  , value       : true
  , callback    : function (value) { host = value; } // override host value
  },
  { short       : 'p'
  , long        : 'port'
  , description : 'The port to connect to'
  , value       : true
  },
];

opts.parse(options, true);

var port  = opts.get('port') || 8000 // default port value
  , debug = opts.get('d') || 'info'  // default debug value
  , file  = opts.get('f')
  , list  = opts.get('list');

var arg1 = opts.args()[0]
  , arg2 = opts.args()[1];


if (list) console.log('List arg was set');
if (file) console.log('File arg was set: ' + file);
console.log('Debug level is: ' + debug);
console.log('Host is: ' + host);
console.log('Port is: ' + port);

if (arg1) console.log('Extra arg 1: ' + arg1);
if (arg2) console.log('Extra arg 2: ' + arg2);

process.exit(0);

Conflict detection

opts/examples/example3.js

/**
 * Simple example that is broken by design (conflicting options)
 *
 * Examples:
 *   $ node example3.js
 *   > Conflicting flags: -v
 */

var opts = require('opts');

var options = [
  { short       : 'v'
  , description : 'Show version and exit'
  },
  { short       : 'v'
  , description : 'Be verbose'
  },
];

opts.parse(options);
console.log('Example 3');
process.exit(0);

Using named arguments and from within a library

opts/examples/example4.js

/**
 * Advanced example using namespaces for a library and named arguments
 *
 * Run:
 *   node example4.js --help
 * and play with the options to see the behavior.
 */

var opts = require('opts')
  , host = 'localhost'; // default host value

// Example of using some library in the same app
var libOpts = [
  { short       : 'l'
  , long        : 'list'
  , description : 'Show the library list'
  , callback    : function () { console.log('mylib list!'); },
  },
];
opts.add(libOpts, 'mylib');

var options = [
  { short       : 'l' // deliberately conflicting with 'mylib' option
  , long        : 'list'
  , description : 'List all files'
  },
  { short       : 'd'
  , long        : 'debug'
  , description : 'Set a debug level'
  , value       : true
  },
];

var arguments = [ { name : 'script' , required : true }
                , { name : 'timeout' }
                ];

opts.parse(options, arguments, true);

var debug = opts.get('d') || 'info'  // default debug value
  , list  = opts.get('list');

var script  = opts.arg('script')
  , timeout = opts.arg('timeout') || 30;


if (list) console.log('List arg was set');
console.log('Debug level is: ' + debug);
console.log('Script is: ' + script);
console.log('Timeout is: ' + timeout);

process.exit(0);

You can find the source code and all examples at Github, github.com/khtdr/opts.