Flag options

Name

With the name you can specify the name of the flag. The name is also used as property name for the options object.

Type

With the type you specify the type of the argument. The type can be one of the following types or any custom types.

• boolean
• string
• number
• integer

The type option is optional. If no type is specified the flag is a boolean option without a value. If type is set to boolean the flag can have a boolean value.

Optional value

by default the value is required for all options with an explicitly defined type. You can make the value optional by setting optionalValue to true.

Variadic value

You can make an argument variadic with the variadic option. A variadic value can occur multiple times and is collected in an array.

List value

If list is set to true, the argument will be splittet by , and the values will be stored in an array. You can overide the seperator with the seperator option.

Aliases

You can specify some aliases for the flag with the aliases option.

Standalone

If standalone is set to true, this option cannot be combined with other options.

If the standalone option is set to true, the option cannot be combined with other options. If additionally an option action handler is defined, only the option action handler is executed and not the command action handler.

Default

The default option specifies the default value for the flag when the flag is not specified on commandline.

Required

If required is set to true an error is throw if the flag is not set on commandline.

Depends

You can specify flags which must be provided if a specific flag is set. If depends is set to ["foo", "bar"], an error is throw if one of this flags are not provided on commandline.

Conflicts

This is the opposite of the conflicts option. You can specify flags which can not be provided if a specific flag is set. If conflicts is set to ["foo", "bar"], an error is throw if one of this flags is provided on commandline.

Equals sign

If equalsSign is set to true the option must be call with an equals sign --foo=bar.

Collect values

If collect is enabled, an flag can be specified multiple times on commandline. All values will be collected in to an array.

import { parseFlags } from "@cliffy/flags";

const { flags } = parseFlags(Deno.args, {
  flags: [{
    name: "color",
    type: "string",
    collect: true,
  }],
});

console.log(flags);Copy

$ deno run examples/flags/collect.ts --color red --color blue
{ color: ["red", "blue"] }Copy

Map values

You may specify a function to do custom processing of flag values. The callback function receives one parameter, the user specified value which is already parsed into the specified type. The return value of this method will be used as flag value.

If collect is enabled the function receives as second parameter the previous value. This allows you to coerce the option value to the desired type, or accumulate values, or do entirely custom processing.

import { parseFlags, ValidationError } from "@cliffy/flags";

const { flags } = parseFlags(Deno.args, {
  flags: [{
    name: "color",
    type: "string",
    collect: true,
    value(value: string, previous: Array<string>): Array<string> | undefined {
      if (["foo", "bar", "baz"].includes(value)) {
        return [...previous, value];
      }
      // if no value is returned, a default validation error will be thrown.
      // You can use the `ValidationError` to provide a custom error message.
      throw new ValidationError(
        `Option "--value" must be one of "foo", "bar" or "baz", but got "${value}".`,
      );
    },
  }],
});

console.log(flags);Copy

$ deno run examples/flags/value.ts --value fooo
error: Uncaught Error: Option "--value" must be one of "foo", "bar" or "baz", but got "fooo".
$ deno run examples/flags/value.ts --value foo
{ value: ["foo"] }Copy

Args

The args array can be used if the flag has multiple values. Following options can be set for each argument:

• type
• optional (see optionalValue)
• variadic
• list

Ignore defaults

The ignoreDefaults option can be used to ignore the default values from specific options. The ignoreDefaults option is an object. The keys have to match the option name but the value can be anything (values are ignored).