Arg

Simple argument parsing

vercel/argarg

README

Arg


arg is an unopinionated, no-frills CLI argument parser.

Installation


  1. ``` sh
  2. npm install arg
  3. ```

Usage


arg() takes either 1 or 2 arguments:

1. Command line specification object (see below)
2. Parse options (_Optional_, defaults to {permissive: false, argv: process.argv.slice(2), stopAtPositional: false})

It returns an object with any values present on the command-line (missing options are thus
missing from the resulting object). Arg performs no validation/requirement checking - we
leave that up to the application.

All parameters that aren't consumed by options (commonly referred to as "extra" parameters)
are added to result._, which is _always_ an array (even if no extra parameters are passed,
in which case an empty array is returned).

  1. ``` js
  2. const arg = require('arg');

  4. // `options` is an optional parameter
  5. const args = arg(
  6. spec,
  7. (options = { permissive: false, argv: process.argv.slice(2) })
  8. );
  9. ```

For example:

  1. ```console
  2. $ node ./hello.js --verbose -vvv --port=1234 -n 'My name' foo bar --tag qux --tag=qix -- --foobar
  3. ```

  1. ``` js
  2. // hello.js
  3. const arg = require('arg');

  5. const args = arg({
  6. // Types
  7. '--help': Boolean,
  8. '--version': Boolean,
  9. '--verbose': arg.COUNT, // Counts the number of times --verbose is passed
  10. '--port': Number, // --port or --port=
  11. '--name': String, // --name or --name=
  12. '--tag': [String], // --tag or --tag=

  14. // Aliases
  15. '-v': '--verbose',
  16. '-n': '--name', // -n ; result is stored in --name
  17. '--label': '--name' // --label or --label=;
  18. //     result is stored in --name
  19. });

  21. console.log(args);
  22. /*
  23. {
  24. _: ["foo", "bar", "--foobar"],
  25. '--port': 1234,
  26. '--verbose': 4,
  27. '--name': "My name",
  28. '--tag': ["qux", "qix"]
  29. }
  30. */
  31. ```

The values for each key=>value pair is either a type (function or [function]) or a string (indicating an alias).

- In the case of a function, the string value of the argument's value is passed to it,
  and the return value is used as the ultimate value.

- In the case of an array, the only element _must_ be a type function. Array types indicate
  that the argument may be passed multiple times, and as such the resulting value in the returned
  object is an array with all of the values that were passed using the specified flag.

- In the case of a string, an alias is established. If a flag is passed that matches the _key_,
  then the _value_ is substituted in its place.

Type functions are passed three arguments:

1. The parameter value (always a string)
2. The parameter name (e.g. --label)
3. The previous value for the destination (useful for reduce-like operations or for supporting -v multiple times, etc.)

This means the built-in String, Number, and Boolean type constructors "just work" as type functions.

Note that Boolean and [Boolean] have special treatment - an option argument is _not_ consumed or passed, but instead true is
returned. These options are called "flags".

For custom handlers that wish to behave as flags, you may pass the function through arg.flag():

  1. ``` js
  2. const arg = require('arg');

  4. const argv = [
  5. '--foo',
  6. 'bar',
  7. '-ff',
  8. 'baz',
  9. '--foo',
  10. '--foo',
  11. 'qux',
  12. '-fff',
  13. 'qix'
  14. ];

  16. function myHandler(value, argName, previousValue) {
  17. /* `value` is always `true` */
  18. return 'na ' + (previousValue || 'batman!');
  19. }

  21. const args = arg(
  22. {
  23.   '--foo': arg.flag(myHandler),
  24.   '-f': '--foo'
  25. },
  26. {
  27.   argv
  28. }
  29. );

  31. console.log(args);
  32. /*
  33. {
  34. _: ['bar', 'baz', 'qux', 'qix'],
  35. '--foo': 'na na na na na na na na batman!'
  36. }
  37. */
  38. ```

As well, arg supplies a helper argument handler called arg.COUNT, which equivalent to a [Boolean] argument's .length
property - effectively counting the number of times the boolean flag, denoted by the key, is passed on the command line..
For example, this is how you could implement ssh's multiple levels of verbosity (-vvvv being the most verbose).

  1. ``` js
  2. const arg = require('arg');

  4. const argv = ['-AAAA', '-BBBB'];

  6. const args = arg(
  7. {
  8.   '-A': arg.COUNT,
  9.   '-B': [Boolean]
  10. },
  11. {
  12.   argv
  13. }
  14. );

  16. console.log(args);
  17. /*
  18. {
  19. _: [],
  20. '-A': 4,
  21. '-B': [true, true, true, true]
  22. }
  23. */
  24. ```

Options


If a second parameter is specified and is an object, it specifies parsing options to modify the behavior of arg().

argv


If you have already sliced or generated a number of raw arguments to be parsed (as opposed to letting arg
slice them from process.argv) you may specify them in the argv option.

For example:

  1. ``` js
  2. const args = arg(
  3. {
  4.   '--foo': String
  5. },
  6. {
  7.   argv: ['hello', '--foo', 'world']
  8. }
  9. );
  10. ```

results in:

  1. ``` js
  2. const args = {
  3. _: ['hello'],
  4. '--foo': 'world'
  5. };
  6. ```

permissive


When permissive set to true, arg will push any unknown arguments
onto the "extra" argument array (result._) instead of throwing an error about
an unknown flag.

For example:

  1. ``` js
  2. const arg = require('arg');

  4. const argv = [
  5. '--foo',
  6. 'hello',
  7. '--qux',
  8. 'qix',
  9. '--bar',
  10. '12345',
  11. 'hello again'
  12. ];

  14. const args = arg(
  15. {
  16.   '--foo': String,
  17.   '--bar': Number
  18. },
  19. {
  20.   argv,
  21.   permissive: true
  22. }
  23. );
  24. ```

results in:

  1. ``` js
  2. const args = {
  3. _: ['--qux', 'qix', 'hello again'],
  4. '--foo': 'hello',
  5. '--bar': 12345
  6. };
  7. ```

stopAtPositional


When stopAtPositional is set to true, arg will halt parsing at the first
positional argument.

For example:

  1. ``` js
  2. const arg = require('arg');

  4. const argv = ['--foo', 'hello', '--bar'];

  6. const args = arg(
  7. {
  8.   '--foo': Boolean,
  9.   '--bar': Boolean
  10. },
  11. {
  12.   argv,
  13.   stopAtPositional: true
  14. }
  15. );
  16. ```

results in:

  1. ``` js
  2. const args = {
  3. _: ['hello', '--bar'],
  4. '--foo': true
  5. };
  6. ```

Errors


Some errors that arg throws provide a .code property in order to aid in recovering from user error, or to
differentiate between user error and developer error (bug).

ARG_UNKNOWN_OPTION

If an unknown option (not defined in the spec object) is passed, an error with code ARG_UNKNOWN_OPTION will be thrown:

  1. ``` js
  2. // cli.js
  3. try {
  4. require('arg')({ '--hi': String });
  5. } catch (err) {
  6. if (err.code === 'ARG_UNKNOWN_OPTION') {
  7.   console.log(err.message);
  8. } else {
  9.   throw err;
  10. }
  11. }
  12. ```

  1. ``` sh
  2. node cli.js --extraneous true
  3. Unknown or unexpected option: --extraneous
  4. ```

FAQ


A few questions and answers that have been asked before:

How do I require an argument with arg?


Do the assertion yourself, such as:

  1. ``` js
  2. const args = arg({ '--name': String });

  4. if (!args['--name']) throw new Error('missing required argument: --name');
  5. ```

License


Released under the MIT License.