arguments

arguments

Arguments are unnamed parameters that are passed to a command.

Note: Currently, arguments and subcommands are not compatible. If you plan to use subcommands, create your arguments as options instead.

Usage

Format

Arguments can be provided in one of three ways:

• single - a single argument
• multiple - multiple arguments passed as an array to a single named argument
• positional - arguments passed in a specific order, each with their own properties

Single Argument

The simplest form of an argument is a single named argument. There is one argument accepted and it is applied to the command data object by the name provided.

{
  arguments: {
    name: 'name'
  }
}

Multiple Arguments

Multiple arguments can be passed to a single named argument by marking it as multiple. This will create an array of values for the named argument.

{
  arguments: {
    name: 'name',
    multiple: true
  }
}

Positional Arguments

Positional arguments are passed in a specific order, with each applied to the data object by its name property. Each argument can have its own properties, such as required or default.

{
  arguments: [
    {
      name: 'name',
      required: true
    },
    {
      name: 'pathFrom'
    },
    {
      name: 'pathTo'
    }
  ]
}

Notes:

• Required Arguments
  • Beginning argument(s) can be marked as required, but no required argument can be provided after one that is optional.
• Variadic/Multiple Arguments
  • Within positional arguments, the last item (and only the last item) can be variadic, meaning it acts as a catch-all for all remaining arguments. This is accomplished by marking it as multiple.

Properties

Property	Required	Type(s)	Default	Description
name	Y	string		Argument name
type	N	string/function	string	Value type
description	N	string		Description
required	N	boolean	false	Required flag
multiple	N	boolean	false	Multiple flag
default	N	any		Default value
tags	N	string/array		Tag(s) to apply in details
validate	N	function		Function to validate value

name: string
type?: any
description?: string
required?: boolean
multiple?: boolean
default?: any
tags?: string | string[]
validate?: (v) => Promise<boolean>

name

The name of the argument. This is the key that the value will be stored under in the command data object.

{
  arguments: {
    name: 'name'
  }
}

type

The type of the argument. This can be a string or a function. If a function is provided, it will be used to parse the value. Default is string.

Common values for type include:

• string
• number
• boolean
• array
• object

{
  arguments: {
    name: 'name',
    type: 'string'
  }
}

{
  arguments: {
    name: 'name',
    type: (v) => v.toUpperCase()
  }
}

description

A description of the argument. This is used in the help menu to describe the argument to the user.

{
  arguments: {
    name: 'name',
    description: 'The name of the thing'
  }
}

required

A flag to indicate if the argument is required. If set to true, the argument must be provided by the user.

{
  arguments: {
    name: 'name',
    required: true
  }
}

multiple

A flag to indicate if the argument can accept multiple values. If set to true, the argument will be stored as an array of values.

{
  arguments: {
    name: 'name',
    multiple: true
  }
}

default

A default value for the argument. If the argument is not provided by the user, the default value will be used.

{
  arguments: {
    name: 'name',
    default: 'default'
  }
}

tags

A tag or array of tags to apply to the argument. These tags can be used to filter arguments in the help menu.

{
  arguments: {
    name: 'name',
    tags: 'foo'
  }
}

{
  arguments: {
    name: 'name',
    tags: ['foo', 'bar']
  }
}

validate

A function to validate the value of the argument. The function should return a boolean value indicating if the value is valid.

{
  arguments: {
    name: 'name',
    validate: (v) => v.length > 0
  }
}

{
  arguments: {
    name: 'name',
    validate: async (v) => {
      const result = await someAsyncValidation(v)
      return result
    }
  }
}

Examples

Single Argument

new Command({
  name: 'copy',
  arguments: {
    name: 'name'
  },
  action: async (data, details) => console.log(data)
})

$ copy foo
{
  name: 'foo'
}

Multiple Arguments

new Command({
  name: 'copy',
  arguments: {
    name: 'name',
    multiple: true
  },
  action: async (data, details) => console.log(data)
})

$ copy foo bar baz
{
  name: ['foo', 'bar', 'baz']
}

Positional Arguments

new Command({
  name: 'copy',
  arguments: [
    {
      name: 'name',
      required: true
    },
    {
      name: 'pathFrom'
    },
    {
      name: 'pathTo'
    }
  ],
  action: async (data, details) => console.log(data)
})

$ copy foo /path/to/file /path/to/destination
{
  name: 'foo',
  pathFrom: '/path/to/file',
  pathTo: '/path/to/destination'
}

Variadic Argument

new Command({
  name: 'copy',
  arguments: [
    {
      name: 'name',
      required: true
    },
    {
      name: 'pathFrom'
    },
    {
      name: 'pathTo',
      multiple: true
    }
  ],
  action: async (data, details) => console.log(data)
})

$ copy foo /path/to/file /path/to/destination1 /path/to/destination2
{
  name: 'foo',
  pathFrom: '/path/to/file',
  pathTo: ['/path/to/destination1', '/path/to/destination2']
}