Parse options

By default the parseFlags method parses all flags and tries to autodetect the type. With the flags option you can specify an Array of flag options. If the flags option is set the parseFlags method will throw an error for all unknown or invalid flags. You can find a list of all possible flag options here.

The args option accepts an array of ArgumentOptions objects that define the expected positional arguments. When defined, non-flag tokens are validated and typed as positional arguments instead of being added to the unknown array. A Error is thrown if more positional arguments are provided than defined.

See positional arguments for usage examples.

With the parse method you can add a custom handler for handling and parsing types.

i

NOTE

The parse method will be called for all types, which means it overrides also all built-in types!

denonodebun

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

parseFlags(Deno.args, {
  flags: [{
    name: "foo",
    type: "float",
  }],
  parse: ({ label, name, value, type }: ArgumentValue) => {
    switch (type) {
      case "float":
        if (isNaN(Number(value))) {
          throw new Error(
            `${label} "${name}" must be of type "${type}", but got "${value}".`,
          );
        }
        return parseFloat(value);
      default:
        throw new Error(`Unknown type "${type}".`);
    }
  },
});

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

parseFlags(process.argv.slice(2), {
  flags: [{
    name: "foo",
    type: "float",
  }],
  parse: ({ label, name, value, type }: ArgumentValue) => {
    switch (type) {
      case "float":
        if (isNaN(Number(value))) {
          throw new Error(
            `${label} "${name}" must be of type "${type}", but got "${value}".`,
          );
        }
        return parseFloat(value);
      default:
        throw new Error(`Unknown type "${type}".`);
    }
  },
});

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

parseFlags(Bun.argv.slice(2), {
  flags: [{
    name: "foo",
    type: "float",
  }],
  parse: ({ label, name, value, type }: ArgumentValue) => {
    switch (type) {
      case "float":
        if (isNaN(Number(value))) {
          throw new Error(
            `${label} "${name}" must be of type "${type}", but got "${value}".`,
          );
        }
        return parseFloat(value);
      default:
        throw new Error(`Unknown type "${type}".`);
    }
  },
});

denonodebun

$ deno run https://cliffy.io/examples/v1.3.1/flags/custom_option_processing.ts --foo 1.2
{ flags: { foo: 1.2 }, unknown: [], literal: [] }

$ deno run https://cliffy.io/examples/v1.3.1/flags/custom_option_processing.ts --foo abc
error: Uncaught Error: Option "--foo" must be of type "float", but got "abc".

$ node run examples/flags/custom_option_processing.ts --foo 1.2
{ flags: { foo: 1.2 }, unknown: [], literal: [] }

$ node run examples/flags/custom_option_processing.ts --foo abc
error: Uncaught Error: Option "--foo" must be of type "float", but got "abc".

$ bun run examples/flags/custom_option_processing.ts --foo 1.2
{ flags: { foo: 1.2 }, unknown: [], literal: [] }

$ bun run examples/flags/custom_option_processing.ts --foo abc
error: Uncaught Error: Option "--foo" must be of type "float", but got "abc".

The option callback method is called for each parsed option.

If stopEarly is enabled, all values starting from the first non option argument are no longer parsed as options. Values that match an expected argument are typed and added to the args array, and all remaining values are added to the unknown array (can be combined with stopOnUnknown).

Without expected arguments, all values are added to the unknown array.

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

const argv = ["--debug-level", "warning", "server", "--port", "80"];
const flags = [{ name: "debug-level", type: "string" }];

const withArgs = parseFlags(argv, {
  stopEarly: true,
  flags,
  args: [
    { name: "script", type: "string" },
    { name: "args", type: "string", variadic: true, optional: true },
  ],
});
// withArgs.args -> [ "server", "--port", "80" ]
// withArgs.unknown -> []

const withoutArgs = parseFlags(argv, { stopEarly: true, flags });
// withoutArgs.unknown -> [ "server", "--port", "80" ]

If stopOnUnknown is enabled, all values starting from the first unknown option argument are no longer parsed as options. They are matched against the expected arguments the same way as with stopEarly, and everything left over is added to the unknown array.

If a required option is specified, by default an error is thrown if the command is invoked without any flags. To disable this behavior you can set allowEmpty to true. The default is false.

By default, all option names that have dots in their names are converted to nested objects. For example, { "foo.bar": 1 } becomes { "foo": { "bar": 1 } }. You can disable this behavior by setting the dotted option to false. This is required when parsing command line arguments in multiple steps (see parse-context).