Flag options

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

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.

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.

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

If list is set to true, the argument will be split by , and the values will be stored in an array. You can override the separator with the separator option.

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

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.

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

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

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

This is the opposite of the depends 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 thrown if one of this flags is provided on commandline.

Conflicts are only checked against explicitly provided flags (as command line argument or environment variable). A conflicting flag that only has its default value does not trigger an error.

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

This only has an effect for options with an optional value. For options with a required value, equalsSign has no effect, the option can always be called with or without an equals sign.

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

denonodebun

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

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

console.log(flags);

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

const { flags } = parseFlags(process.argv.slice(2), {
  flags: [{
    name: "color",
    type: "string",
    collect: true,
  }],
});

console.log(flags);

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

const { flags } = parseFlags(Bun.argv.slice(2), {
  flags: [{
    name: "color",
    type: "string",
    collect: true,
  }],
});

console.log(flags);

denonodebun

$ deno run https://cliffy.io/examples/v1.2.1/flags/collect.ts --color red --color blue
{ color: ["red", "blue"] }

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

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

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.

denonodebun

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);

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

const { flags } = parseFlags(process.argv.slice(2), {
  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);

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

const { flags } = parseFlags(Bun.argv.slice(2), {
  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);

denonodebun

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

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

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

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

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).