Skip to content

Flag

Defines named options for command-line applications.

A Flag<A> describes how to read one named value from parsed command-line input, validate it, and produce an A. Flags are useful for inputs such as ports, verbosity switches, configuration files, output directories, choices, secrets, and repeated values. The helpers here build flags with aliases, defaults, optional values, prompts, configuration fallbacks, validation, and value transformations.

36 exports Added in v4.0.0 Source

Aliasing

withAlias

Added in v4.0.0 Source

Adds an alias to a flag, allowing it to be referenced by multiple names.

Signature

declare const withAlias: {
  <A>(alias: string): (self: Flag<A>) => Flag<A>;
  <A>(self: Flag<A>, alias: string): Flag<A>;
};

Alternatives

orElse

Added in v4.0.0 Source

Provides an alternative flag if the first one fails to parse.

Signature

declare const orElse: {
  <B>(that: LazyArg<Flag<B>>): <A>(self: Flag<A>) => Flag<B | A>;
  <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>): Flag<A | B>;
};

orElseResult

Added in v4.0.0 Source

Tries to parse with the first flag, then the second, returning a Result that indicates which succeeded.

Signature

declare const orElseResult: {
  <B>(that: LazyArg<Flag<B>>): <A>(self: Flag<A>) => Flag<Result<A, B>>;
  <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>): Flag<Result<A, B>>;
};

Combinators

withFallbackConfig

Added in v4.0.0 Source

Adds a fallback config that is loaded when a required flag is missing.

Signature

declare const withFallbackConfig: {
  <B>(config: Config<B>): <A>(self: Flag<A>) => Flag<B | A>;
  <A, B>(self: Flag<A>, config: Config<B>): Flag<A | B>;
};

withFallbackPrompt

Added in v4.0.0 Source

Adds a fallback prompt that is shown when a required flag is missing.

Signature

declare const withFallbackPrompt: {
  <B>(prompt: FallbackPrompt<B>): <A>(self: Flag<A>) => Flag<B | A>;
  <A, B>(self: Flag<A>, prompt: FallbackPrompt<B>): Flag<A | B>;
};

Constructors

boolean

Added in v4.0.0 Source

Creates a boolean flag that can be enabled or disabled.

Signature

declare function boolean(name: string): Flag<boolean>;

choice

Added in v4.0.0 Source

Creates a flag that accepts one of the provided string choices and returns the selected string.

When to use

Use when you need to define a named CLI flag with fixed string choices and no custom value mapping.

Gotchas

An empty choices array compiles, but no input value can parse successfully.

See

Signature

declare function choice<Choices extends readonly Array<string>>(name: string, choices: Choices): Flag<Choices[number]>

choiceWithValue

Added in v4.0.0 Source

Constructs option parameters that represent a choice between several inputs. Each tuple maps a string flag value to an associated typed value.

Signature

declare function choiceWithValue<Choice extends readonly Array<readonly [string, any]>>(name: string, choices: Choice): Flag<Choice[number][1]>

date

Added in v4.0.0 Source

Creates a date flag that accepts date input in ISO format.

Signature

declare function date(name: string): Flag<Date>;

directory

Added in v4.0.0 Source

Creates a directory path flag that accepts directory paths with optional existence validation.

Signature

declare function directory(
  name: string,
  options?: {
    readonly mustExist?: boolean;
  },
): Flag<string>;

file

Added in v4.0.0 Source

Creates a file path flag that accepts file paths with optional existence validation.

Signature

declare function file(
  name: string,
  options?: {
    readonly mustExist?: boolean;
  },
): Flag<string>;

fileParse

Added in v4.0.0 Source

Creates a flag that reads and parses the content of the specified file.

Details

The parser that is utilized will depend on the specified format, or the extension of the file passed on the command-line if no format is specified.

Signature

declare function fileParse(name: string, options?: FileParseOptions): Flag<unknown>;

fileSchema

Added in v4.0.0 Source

Creates a flag that reads and validates file content using the specified schema.

Signature

declare function fileSchema<A>(
  name: string,
  schema: ConstraintDecoder<A, Environment>,
  options?: {
    readonly errorFormatter?: Formatter<string>;
    readonly format?: "json" | "ini" | "toml" | "yaml";
  },
): Flag<A>;

fileText

Added in v4.0.0 Source

Creates a flag that reads and returns file content as a string.

Signature

declare function fileText(name: string): Flag<string>;

float

Added in v4.0.0 Source

Creates a float flag that accepts decimal number input.

Signature

declare function float(name: string): Flag<number>;

integer

Added in v4.0.0 Source

Creates an integer flag that accepts whole number input.

Signature

declare function integer(name: string): Flag<number>;

keyValuePair

Added in v4.0.0 Source

Creates a flag that parses key=value pairs.

When to use

Use when you need a CLI flag that accepts one or more key=value configuration entries.

Details

Requires at least one key=value pair. Multiple pairs are merged into a single record.

Signature

declare function keyValuePair(name: string): Flag<Record<string, string>>;

none

Added in v4.0.0 Source

Creates an empty sentinel flag that always fails to parse. This is useful for creating placeholder flags or for combinators.

Signature

declare const none: Flag<never>;

path

Added in v4.0.0 Source

Creates a path flag that accepts file system path input with validation options.

Signature

declare function path(
  name: string,
  options?: {
    readonly mustExist?: boolean;
    readonly pathType?: "either" | "file" | "directory";
    readonly typeName?: string;
  },
): Flag<string>;

redacted

Added in v4.0.0 Source

Creates a string flag whose parsed value is wrapped in Redacted.Redacted so stringification and logging redact the value.

Gotchas

Values supplied on the command line may still be visible to the operating system or shell history.

Signature

declare function redacted(name: string): Flag<Redacted<string>>;

string

Added in v4.0.0 Source

Creates a string flag that accepts text input.

Signature

declare function string(name: string): Flag<string>;

Filtering

filter

Added in v4.0.0 Source

Filters a flag value based on a predicate, failing with a custom error if the predicate returns false.

Signature

declare const filter: {
  <A>(predicate: (a: A) => boolean, onFalse: (a: A) => string): (self: Flag<A>) => Flag<A>;
  <A>(self: Flag<A>, predicate: (a: A) => boolean, onFalse: (a: A) => string): Flag<A>;
};

filterMap

Added in v4.0.0 Source

Transforms and filters a flag value, failing with a custom error if the transformation returns None.

Signature

declare const filterMap: {
  <A, B>(f: (a: A) => Option<B>, onNone: (a: A) => string): (self: Flag<A>) => Flag<B>;
  <A, B>(self: Flag<A>, f: (a: A) => Option<B>, onNone: (a: A) => string): Flag<B>;
};

Mapping

map

Added in v4.0.0 Source

Transforms the parsed value of a flag using a mapping function.

Signature

declare const map: {
  <A, B>(f: (a: A) => B): (self: Flag<A>) => Flag<B>;
  <A, B>(self: Flag<A>, f: (a: A) => B): Flag<B>;
};

mapEffect

Added in v4.0.0 Source

Transforms the parsed value using an Effect that can perform IO operations.

Signature

declare const mapEffect: {
  <A, B>(f: (a: A) => Effect<B, CliError, Environment>): (self: Flag<A>) => Flag<B>;
  <A, B>(self: Flag<A>, f: (a: A) => Effect<B, CliError, Environment>): Flag<B>;
};

mapTryCatch

Added in v4.0.0 Source

Transforms the parsed value using a function that might throw, with error handling.

Signature

declare const mapTryCatch: {
  <A, B>(f: (a: A) => B, onError: (error: unknown) => string): (self: Flag<A>) => Flag<B>;
  <A, B>(self: Flag<A>, f: (a: A) => B, onError: (error: unknown) => string): Flag<B>;
};

Metadata

withDescription

Added in v4.0.0 Source

Adds a description to a flag for help documentation.

Signature

declare const withDescription: {
  <A>(description: string): (self: Flag<A>) => Flag<A>;
  <A>(self: Flag<A>, description: string): Flag<A>;
};

withHidden

Added in v4.0.0 Source

Hides a flag from generated help output and shell completions while keeping it fully parseable on the command line.

When to use

Use when experimental or internal flags should be accepted but not advertised, such as --experimental-foo, debug toggles, or escape hatches that are not yet committed to the public CLI surface.

Signature

declare function withHidden<A>(self: Flag<A>): Flag<A>;

withMetavar

Added in v4.0.0 Source

Sets a custom metavar (placeholder name) for the flag in help documentation.

Details

The metavar is displayed in usage text to indicate what value the user should provide. For example, --output FILE shows FILE as the metavar.

Signature

declare const withMetavar: {
  <A>(metavar: string): (self: Flag<A>) => Flag<A>;
  <A>(self: Flag<A>, metavar: string): Flag<A>;
};

Models

Flag interface

Added in v4.0.0 Source

Represents a command-line flag.

Signature

interface Flag<A> extends Param<typeof Param.flagKind, A> {}

Optionality

optional

Added in v4.0.0 Source

Makes a flag optional, returning an Option type that can be None if not provided.

Signature

declare function optional<A>(param: Flag<A>): Flag<Option<A>>;

withDefault

Added in v4.0.0 Source

Provides a default value for a flag when it's not specified.

Signature

declare const withDefault: {
  <B>(defaultValue: B | Effect<B, CliError, Environment>): <A>(self: Flag<A>) => Flag<B | A>;
  <A, B>(self: Flag<A>, defaultValue: B | Effect<B, CliError, Environment>): Flag<A | B>;
};

Repetition

atLeast

Added in v4.0.0 Source

Ensures a flag is specified at least a minimum number of times.

Signature

declare const atLeast: {
  <A>(min: number): (self: Flag<A>) => Flag<readonly Array<A>>;
  <A>(self: Flag<A>, min: number): Flag<readonly Array<A>>;
}

atMost

Added in v4.0.0 Source

Ensures a flag is specified at most a maximum number of times.

Signature

declare const atMost: {
  <A>(max: number): (self: Flag<A>) => Flag<readonly Array<A>>;
  <A>(self: Flag<A>, max: number): Flag<readonly Array<A>>;
}

between

Added in v4.0.0 Source

Ensures a flag is specified between a minimum and maximum number of times.

Signature

declare const between: {
  <A>(min: number, max: number): (self: Flag<A>) => Flag<readonly Array<A>>;
  <A>(self: Flag<A>, min: number, max: number): Flag<readonly Array<A>>;
}

Schemas

withSchema

Added in v4.0.0 Source

Validates and transforms a flag value using a Schema codec.

Signature

declare const withSchema: {
  <A, B>(schema: ConstraintCodec<B, A, Environment, unknown>): (self: Flag<A>) => Flag<B>;
  <A, B>(self: Flag<A>, schema: ConstraintCodec<B, A, Environment, unknown>): Flag<B>;
};