readFlags

Generated reference page for the readFlags function export.

• Import: @kjanat/dreamcli
• Export kind: function
• Declared in: src/core/read-flags/index.ts
• Source link: src/core/read-flags/index.ts:263

Signatures

function readFlags<F extends Readonly<Record<string, FlagBuilder<FlagConfig>>>>(definitions: F, options?: ReadFlagsOptions): Promise<InferFlags<F>>;

Parameter	Type	Description
definitions	F	Flag builders keyed by canonical flag name.
options	ReadFlagsOptions | undefined	Injected runtime state and behavior toggles.

Members

Members

readFlags

Evaluate a record of flag definitions and return the resolved values.

The record is compiled into an anonymous command schema with no positional arguments, parsed once, and run through the CLI, env, config, prompt, default resolution chain. Aliases, negated spellings, duplicate policy, case parity, unknown-flag rejection, coercion, constraints, Standard Schema validators, and flag.path() checks behave exactly as they do inside a command.

A pre-separator --help or -h prints generated help to the adapter's stdout and exits with code 0, unless ReadFlagsOptions.help is 'off' or a definition claims either spelling. With ReadFlagsOptions.strict set to false, undeclared argv content is dropped instead of rejected, so a script can read its own flags out of an argv it shares with another consumer.

Anything the caller leaves out comes from the runtime adapter, which is built on first use, so a call given argv and env reads nothing from the host unless a flag.path() check needs the adapter's filesystem primitives. config has no application name to discover a file from and stays caller-supplied. prompter stays caller-supplied as well, so a .prompt() flag with no prompter falls through to its default.

(definitions: F, options?: ReadFlagsOptions): Promise<InferFlags<F>>;

Examples

import { flag, readFlags } from '@kjanat/dreamcli';

const options = await readFlags({
  watch: flag.boolean().alias('w').env('WATCH').default(false),
  minify: flag.boolean().env('MINIFY').default(true),
  target: flag.enum(['node', 'browser']).env('TARGET').default('node'),
});

options.watch; // boolean
options.minify; // boolean
options.target; // 'node' | 'browser'

const values = await readFlags(
  { watch: flag.boolean().alias('w').env('WATCH') },
  { argv: [], env: { WATCH: 'true' } },
);

values.watch; // true

const values = await readFlags(
  { watch: flag.boolean() },
  { argv: ['build', '--watch', '--unknown'], env: {}, strict: false },
);

values.watch; // true, with 'build' and '--unknown' dropped

See Also

• Examples overview
• Example Hover
• API overview
• @kjanat/dreamcli