Skip to content

ReadFlagsOptions ​

External state and behavior toggles accepted by readFlags.

Extends ResolveOptions, so env, config, prompter, stat, and mkdir carry the meaning they have during command resolution.

Signatures ​

ts
interface ReadFlagsOptions<F extends FlagMap> extends ResolveOptions {}

Members ​

Properties ​

argv ​

User arguments only, without the binary and script entries.

ts
argv?: readonly string[];

adapter ​

Runtime source for argv, environment, and filesystem primitives.

ts
adapter?: RuntimeAdapter;

parse ​

Parser behavior such as kebab/camel case parity.

ts
parse?: ParseOptions;

strict ​

Reject argv content the definitions do not declare.

false drops undeclared input from argv before parsing: unknown long flags together with their inline =value, unknown characters inside a short group, positional arguments, and the -- separator, which can only introduce positionals here. A value token of a declared flag is kept by walking the same consumption rules the parser applies. Misuse of a declared flag still fails: a missing value, a bad coercion, or a violated duplicate policy throws in either mode.

ts
strict?: boolean;

help ​

The built-in --help/-h/--help=all handling.

While 'on', a pre-separator help flag prints generated help for the definitions to the adapter's stdout and exits the process with code 0. The built-in yields automatically when any definition claims the help or h spelling through its name, an alias, a negated form, or a case-parity counterpart; those spellings then parse as the definition's own. 'off' removes the built-in, and the spellings parse like any other token.

ts
help?: "on" | "off";

flagSpelling ​

Spelling of long flag names, aliases, and negations in generated help.

'kebab' shows --wasm-path for a definition keyed wasmPath, which still resolves as wasmPath. A spelling stays as declared when the parser would not accept its kebab form for the same flag, such as with parse: { caseParity: false }.

ts
flagSpelling?: "declared" | "kebab";

onDeprecation ​

Receiver for notices produced by .deprecated() flags.

ts
onDeprecation?: { (warning: DeprecationWarning): void; };

onSources ​

Receiver for the provenance of the resolved values, keyed by flag name.

Called once with the whole record, before readFlags returns the values. A flag that resolved no value has no record, so the same reader works for optional flags.

ts
onSources?: { (sources: SourcesOf<F>): void; };

stdinData ​

Pre-read stdin content, or null when stdin was not piped.

ts
stdinData?: string | null | undefined;

env ​

Environment variable snapshot injected by the caller.

ts
env?: Readonly<Record<string, string | undefined>> | undefined;

config ​

Parsed config file contents keyed by dotted path segments.

ts
config?: Readonly<Record<string, unknown>> | undefined;

prompter ​

Interactive prompt engine; absent in non-TTY / CI contexts.

ts
prompter?: import("../prompt").PromptEngine | undefined;

stat ​

Filesystem probe for flag.path() and arg.path() checks: what exists at the path, or null when nothing does. When absent, path checks are skipped.

ts
stat?: ((path: string) => Promise<"file" | "directory" | null>) | undefined;

mkdir ​

Recursive directory creation for flag.path() and arg.path() create checks. When absent, missing paths are not created and existence rules apply as-is.

ts
mkdir?: ((path: string) => Promise<void>) | undefined;

pathChecks ​

What happens to a declared filesystem check that cannot run because ResolveOptions.stat (or ResolveOptions.mkdir for create) is absent.

  • 'lenient' — the check is skipped and recorded in ResolveResult.skippedPathChecks, so a result can still report that it was never exercised.
  • 'strict' — resolution fails with a CLIError of code 'PATH_CHECK_SKIPPED' (exit code 1) naming every skipped input, for tests that must exercise each declared check.

Only inputs that resolved a path value are affected: an unset optional path has nothing to check in production either.

ts
pathChecks?: "lenient" | "strict" | undefined;

envPrefix ​

Environment namespace prepended to every relative env binding, the count and templates of an indexed family included. A binding declared absolute is read as written. Diagnostics and provenance name the concrete variable.

ts
envPrefix?: string | undefined;

See Also ​

Released under the MIT License.