Options

A command line option is an argument or arguments in the following formats:

• --long-key value
• --long-key=value
• -s value
• -s=value

where long-key is "the long form key" and s is "a short form key".

There are two ways to parse options:

• The option parser which parses one and only one option
• The multioption parser which parser none or multiple options

option

Parses one and only one option. Accepts a Type from string to any value to decode the users' intent.

In order to make this optional, either the type provided or a defaultValue function should be provided. In order to make a certain type optional, you can take a look at optional

This parser will fail to parse if:

• There are zero options that match the long form key or the short form key
• There are more than one option that match the long form key or the short form key
• No value was provided (if it was treated like a flag)
• Decoding the user input fails

Usage

import { command, number, option } from 'cmd-ts';

const myNumber = option({
  type: number,
  long: 'my-number',
  short: 'n',
});

const cmd = command({
  name: 'my number',
  args: { myNumber },
});

Config

• type (required): A type from string to any value
• long (required): The long form key
• short: The short form key
• description: A short description regarding the option
• displayName: A short description regarding the option
• defaultValue: A function that returns a default value for the option
• defaultValueIsSerializable: Whether to print the defaultValue as a string in the help docs.

multioption

Parses multiple or zero options. Accepts a Type from string[] to any value, letting you do the conversion yourself.

Note: using multioption will drop all the contextual errors. Every error on the type conversion will show up as if all of the options were errored. This is a higher level with less granularity.

This parser will fail to parse if:

• No value was provided (if it was treated like a flag)
• Decoding the user input fails

Config

• type (required): A type from string[] to any value
• long (required): The long form key
• short: The short form key
• description: A short description regarding the option
• displayName: A short description regarding the option
• defaultValue: A function that returns a default value for the option array in case no options were provided. If not provided, the default value will be an empty array.
• defaultValueIsSerializable: Whether to print the defaultValue as a string in the help docs.