Skip to main content
Module

std/flags/README.md

Deno standard library
denoland/deno_std
Go to Latest
File

flags

Command line arguments parser for Deno based on minimist.

Example

import { parse } from "https://deno.land/std@0.147.0/flags/mod.ts";

console.dir(parse(Deno.args));
$ deno run https://deno.land/std/examples/flags.ts -a beep -b boop
{ _: [], a: 'beep', b: 'boop' }
$ deno run https://deno.land/std/examples/flags.ts -x 3 -y 4 -n5 -abc --beep=boop foo bar baz
{ _: [ 'foo', 'bar', 'baz' ],
  x: 3,
  y: 4,
  n: 5,
  a: true,
  b: true,
  c: true,
  beep: 'boop' }

API

const parsedArgs = parse(args, options = {});

parsedArgs._ contains all the arguments that didn’t have an option associated with them.

Numeric-looking arguments will be returned as numbers unless options.string or options.boolean is set for that argument name.

Any arguments after '--' will not be parsed and will end up in parsedArgs._.

options can be:

  • options.string - a string or array of strings argument names to always treat as strings.
  • options.boolean - a boolean, string or array of strings to always treat as booleans. if true will treat all double hyphenated arguments without equal signs as boolean (e.g. affects --foo, not -f or --foo=bar). All boolean arguments will be set to false by default.
  • options.collect - a string or array of strings argument names to always treat as arrays. Collectable options can be used multiple times. All values will be collected into an array. If a non collectable option is used multiple times, the last value is used. All Collectable arguments will be set to [] by default.
  • options.negatable - a string or array of strings argument names which can be negated by prefixing them with --no-, like --no-config.
  • options.alias - an object mapping string names to strings or arrays of string argument names to use as aliases.
  • options.default - an object mapping string argument names to default values.
  • options.stopEarly - when true, populate parsedArgs._ with everything after the first non-option.
  • options['--'] - when true, populate parsedArgs._ with everything before the -- and parsedArgs['--'] with everything after the --. Here’s an example:
    // $ deno run example.ts -- a arg1
import { parse } from "https://deno.land/std@0.147.0/flags/mod.ts";
console.dir(parse(Deno.args, { "--": false }));
// output: { _: [ "a", "arg1" ] }
console.dir(parse(Deno.args, { "--": true }));
// output: { _: [], --: [ "a", "arg1" ] }
  • options.unknown - a function which is invoked with a command line parameter not defined in the options configuration object. If the function returns false, the unknown option is not added to parsedArgs.

By default, the flags module tries to determine the type of all arguments automatically and the return type of the parse method will have an index signature with any as value ({ [x: string]: any }).

If the string, boolean or collect option is set, the return value of the parse method will be fully typed and the index signature of the return type will change to { [x: string]: unknown }.