Skip to content
@staticbolt/args-parser

Context

context records how each value was filled in and what the raw input was. Every handler receives it alongside the parsed values.

cli.onExecute(({ context }) => {
  const option = context.options.listName;


  if (option.source === "terminal") {
    console.log(option.flag, option.stringValues);
  }
});

Context

Field Type Description
subcommand string | undefined The subcommand that ran, if any.
options Record<string, OptionContext> One entry per defined option.
arguments Record<string, ArgumentContext> One entry per defined argument.
positionals string[] | never The raw positionals, when they are allowed.

OptionContext

Property Description
source "terminal", "default", or "programmatic".
schema The schema used to validate it.
optional Whether the schema makes it optional.
defaultValue The schema's default, if it has one.
flag The flag the user typed, such as --list or -l. Terminal only, last one wins.
stringValues The raw strings, one per occurrence. Terminal only.
passedValue The value handed to execute. Programmatic only.

ArgumentContext

Property Description
source "terminal", "default", or "programmatic".
schema The schema used to validate it.
optional Whether the schema makes it optional.
defaultValue The schema's default, if it has one.
stringValue The raw string. Terminal only.
passedValue The value handed to execute. Programmatic only.

Narrowing by source

The fields are typed per source. Check source first and TypeScript gives you only what exists:

cli.onExecute(({ context }) => {
  const option = context.options.items;


  switch (option.source) {
    case "terminal":
      console.log(option.stringValues); // string[]
      break;
    case "programmatic":
      console.log(option.passedValue);
      break;
    case "default":
      console.log(option.defaultValue);
      break;
  }
});