argcat v1.0.2

The simplest CLI arguments parser.

npm install --save-prod argcat

Usage

import { parseArgs } from 'argcat';

const options = parseArgs(process.argv.slice(2));

Arguments prefixed with a '--' are treated as options:

parseArgs(['--foo']);
// ⮕  { foo: [] }

Options can have values:

parseArgs(['--foo', 'bar']);
// ⮕  { foo: ['bar'] }

parseArgs(['--foo', '--qux', 'bar']);
// ⮕  { foo: [], qux: ['bar'] }

If an option is repeated multiple times then all values are captured in an array:

parseArgs(['--foo', 'bar', '--foo', 'qux']);
// ⮕  { foo: ['bar', 'qux'] }

Arguments that aren't prefixed with minus chars are stored under '' key:

parseArgs(['foo', 'bar']);
// ⮕  { '': ['foo', 'bar'] }

There's a special option '--', after which all arguments are stored under '--' key:

parseArgs(['--', '--foo', 'bar']);
// ⮕  { '--': ['--foo', 'bar'] }

Mark an option as a flag to prevent value capturing:

parseArgs(['--foo', 'bar']);
// ⮕  { foo: ['bar'] }

parseArgs(['--foo', 'bar'], { flags: ['foo'] });
// ⮕  { foo: true, '': ['bar'] }

Flag options have true value instead of an array.

Shorthands

By default, shorthand options are ignored:

parseArgs(['-x']);
// ⮕  {}

To preserve shorthands, use keepShorthands option:

parseArgs(['-x'], { keepShorthands: true });
// ⮕  { x: [] }

Multiple shorthands can be combined:

parseArgs(['-abc'], { keepShorthands: true });
// ⮕  { a: [], b: [], c: [] }

Use shorthand mapping to expand shorthands:

parseArgs(['-x'], { shorthands: { x: 'foo' } });
// ⮕  { foo: [] }

Shorthand options can have values:

parseArgs(['-x', 'bar'], { keepShorthands: true });
// ⮕  { x: ['bar'] }

parseArgs(['-abc', 'bar'], { keepShorthands: true });
// ⮕  { a: [], b: [], c: ['bar'] }

Commands

argcat doesn't have a special treatment for commands syntax, but it can be easily emulated:

const argv = ['push', '--tags'];

const result = parseArgs(argv, { flags: ['tags'] });
// ⮕  { '': ['push'], tags: true }

The first element of '' is a command:

const command = result[''].shift();

if (command === 'push') {
  // Push it to the limit
}

Note that this approach allows user to specify options before the command:

const result = parseArgs(['--tags', 'push'], { flags: ['tags'] });
// ⮕  { '': ['push'], tags: true }

Type coercion

Combine argcat with Doubter to validate parsed arguments and to coerce their types.

import { parseArgs } from 'argcat';
import * as d from 'doubter';

// 1️⃣ Define the shape of a CLI options object
const optionsShape = d
  .object({
    age: d.number()
  })
  .strip();

const options = optionsShape.parse(
  // 2️⃣ Convert process.argv.slice(2) to options
  parseArgs(['--age', '42']),
  
  // 3️⃣ Enable type coercion
  { coerce: true }
);
// ⮕  { age: 42 }