Param

Defines the shared parameter model for CLI arguments and flags.

A Param<Kind, A> describes how to consume parsed command-line input and return a typed value. The Kind decides whether the parameter reads positional arguments or named flags. Argument and Flag build on this module to share parsing structure, primitive constructors, help metadata, aliases, defaults, prompts, configuration fallbacks, validation, schema decoding, fallback parameters, and traversal helpers.

57 exports Added in v4.0.0 Source

Combinators

atLeast

Added in v4.0.0 Source

Wraps an option to require it to be specified at least min times.

Details

This combinator transforms an option to accept at least min occurrences on the command line, returning an array of all provided values.

Signature

declare const atLeast: {
  <A>(min: number): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, readonly Array<A>>;
  <Kind extends ParamKind, A>(self: Param<Kind, A>, min: number): Param<Kind, readonly Array<A>>;
}

atMost

Added in v4.0.0 Source

Wraps an option to allow it to be specified at most max times.

Details

This combinator transforms an option to accept between 0 and max occurrences on the command line, returning an array of all provided values.

Signature

declare const atMost: {
  <A>(max: number): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, readonly Array<A>>;
  <Kind extends ParamKind, A>(self: Param<Kind, A>, max: number): Param<Kind, readonly Array<A>>;
}

between

Added in v4.0.0 Source

Wraps an option to allow it to be specified multiple times within a range.

Details

This combinator transforms an option to accept between min and max occurrences on the command line, returning an array of all provided values.

Signature

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

filter

Added in v4.0.0 Source

Filters parsed values, failing with a custom error message if the predicate returns false.

Signature

declare const filter: {
  <A>(
    predicate: Predicate<A>,
    onFalse: (a: A) => string,
  ): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, A>;
  <Kind extends ParamKind, A>(
    self: Param<Kind, A>,
    predicate: Predicate<A>,
    onFalse: (a: A) => string,
  ): Param<Kind, A>;
};

filterMap

Added in v4.0.0 Source

Filters and transforms parsed values, failing with a custom error message if the filter function returns Option.none().

When to use

Use when you need validation and transformation in a single parameter combinator.

Signature

declare const filterMap: {
  <A, B>(
    filter: (a: A) => Option<B>,
    onNone: (a: A) => string,
  ): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
  <Kind extends ParamKind, A, B>(
    self: Param<Kind, A>,
    filter: (a: A) => Option<B>,
    onNone: (a: A) => string,
  ): Param<Kind, B>;
};

map

Added in v4.0.0 Source

Transforms the parsed value of an option using a mapping function.

Signature

declare const map: {
  <A, B>(f: (a: A) => B): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, f: (a: A) => B): Param<Kind, B>;
};

mapEffect

Added in v4.0.0 Source

Transforms the parsed value of an option using an effectful mapping function.

Signature

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

mapTryCatch

Added in v4.0.0 Source

Transforms the parsed value of an option using a function that may throw, converting any thrown errors into failure messages.

Signature

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

optional

Added in v4.0.0 Source

Makes a flag or positional argument optional.

Details

When the parameter is absent, parsing succeeds with Option.none() instead of failing with a missing option or missing argument error. When present, the parsed value is wrapped in Option.some().

Signature

declare function optional<Kind extends ParamKind, A>(param: Param<Kind, A>): Param<Kind, Option<A>>;

orElse

Added in v4.0.0 Source

Provides a fallback param to use if this param fails to parse.

Signature

declare const orElse: {
  <B, Kind extends ParamKind>(
    orElse: LazyArg<Param<Kind, B>>,
  ): <A>(self: Param<Kind, A>) => Param<Kind, B | A>;
  <Kind extends ParamKind, A, B>(
    self: Param<Kind, A>,
    orElse: LazyArg<Param<Kind, B>>,
  ): Param<Kind, A | B>;
};

orElseResult

Added in v4.0.0 Source

Provides a fallback param and returns a Result indicating which param succeeded.

Details

The original param's value is returned as Result.succeed, while the fallback param's value is returned as Result.fail.

Signature

declare const orElseResult: {
  <Kind extends ParamKind, B>(
    orElse: LazyArg<Param<Kind, B>>,
  ): <A>(self: Param<Kind, A>) => Param<Kind, Result<A, B>>;
  <Kind extends ParamKind, A, B>(
    self: Param<Kind, A>,
    orElse: LazyArg<Param<Kind, B>>,
  ): Param<Kind, Result<A, B>>;
};

variadic

Added in v4.0.0 Source

Creates a variadic parameter that can be specified multiple times.

Details

This is the base combinator for creating parameters that accept multiple values. The min and max parameters are optional. When they are not provided, the parameter can be specified any number of times, from 0 to infinity.

Signature

declare function variadic<Kind extends ParamKind, A>(self: Param<Kind, A>, options?: VariadicParamOptions): Param<Kind, readonly Array<A>>

withAlias

Added in v4.0.0 Source

Adds an alias to an option.

When to use

Use when you need a CLI parameter to accept an alternate name, such as "-f" for "--force".

Details

This works on any param structure by recursively finding the underlying Single node and applying the alias there.

Signature

declare const withAlias: {
  <Kind extends ParamKind, A>(alias: string): (self: Param<Kind, A>) => Param<Kind, A>;
  <Kind extends ParamKind, A>(self: Param<Kind, A>, alias: string): Param<Kind, A>;
};

withDefault

Added in v4.0.0 Source

Makes a flag or positional argument optional by supplying a fallback value.

Details

The fallback may be a pure value or an effect. It is used only when the parameter is absent; provided values are parsed normally.

Signature

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

withDescription

Added in v4.0.0 Source

Adds a description to an option for help text.

Details

Descriptions provide users with information about what the option does when they view help documentation.

Signature

declare const withDescription: {
  <Kind extends ParamKind, A>(description: string): (self: Param<Kind, A>) => Param<Kind, A>;
  <Kind extends ParamKind, A>(self: Param<Kind, A>, description: string): Param<Kind, A>;
};

withFallbackConfig

Added in v4.0.0 Source

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

When to use

Use when you need config to provide a fallback source for required flags or arguments that are absent from CLI input.

Details

Provided CLI values win. Config is loaded only after a missing option or missing argument error.

Gotchas

Missing config preserves the original missing-parameter error. Config parse failure becomes CliError.InvalidValue.

See

withDefault for a pure default value
withFallbackPrompt for prompting interactively when input is missing

Signature

declare const withFallbackConfig: {
  <B>(config: Config<B>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, B | A>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, config: Config<B>): Param<Kind, A | B>;
};

withFallbackPrompt

Added in v4.0.0 Source

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

When to use

Use when a CLI should ask interactively for a missing required flag or argument.

Details

FallbackPrompt accepts either a Prompt or an effect that builds one. Effectful prompt creation is lazy and runs only when the fallback is needed.

Gotchas

This only handles missing options and missing arguments. Invalid values do not prompt, and prompt cancellation re-fails with the original missing error.

See

FallbackPrompt for accepted fallback prompt forms
withFallbackConfig for loading a fallback from config
withDefault for a pure default value

Signature

declare const withFallbackPrompt: {
  <B>(
    prompt: FallbackPrompt<B>,
  ): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, B | A>;
  <Kind extends ParamKind, A, B>(
    self: Param<Kind, A>,
    prompt: FallbackPrompt<B>,
  ): Param<Kind, A | B>;
};

withSchema

Added in v4.0.0 Source

Validates parsed values against a Schema, providing detailed error messages.

Signature

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

Constants

argumentKind

Added in v4.0.0 Source

Defines the kind discriminator for positional argument parameters.

When to use

Use to build low-level Param constructors or type positions for positional argument parameters.

See

flagKind for the named flag parameter discriminator
ParamKind for the full parameter kind union

Signature

declare const argumentKind: "argument";

flagKind

Added in v4.0.0 Source

Defines the kind discriminator for flag parameters.

When to use

Use to build low-level Param constructors or type positions for named flag parameters.

See

argumentKind for the positional argument parameter discriminator

Signature

declare const flagKind: "flag";

Constructors

boolean

Added in v4.0.0 Source

Creates a boolean parameter.

Signature

declare function boolean<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, boolean>;

choice

Added in v4.0.0 Source

Constructs command-line params that represent a choice between several string inputs.

Signature

declare function choice<Kind extends ParamKind, Choices extends readonly Array<string>>(kind: Kind, name: string, choices: Choices): Param<Kind, Choices[number]>

choiceWithValue

Added in v4.0.0 Source

Constructs command-line params that represent a choice between several inputs. The input will be mapped to it's associated value during parsing.

Signature

declare function choiceWithValue<Kind extends ParamKind, Choices extends readonly Array<readonly [string, any]>>(kind: Kind, name: string, choices: Choices): Param<Kind, Choices[number][1]>

date

Added in v4.0.0 Source

Creates a date parameter that parses ISO date strings.

Signature

declare function date<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, Date>;

file

Added in v4.0.0 Source

Creates a file path parameter.

Details

This is a convenience function that creates a path parameter with a pathType set to "file" and a default type name of "file".

Signature

declare function file<Kind extends ParamKind>(
  kind: Kind,
  name: string,
  options?: {
    readonly mustExist?: boolean;
  },
): Param<Kind, string>;

fileParse

Added in v4.0.0 Source

Creates a param 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<Kind extends ParamKind>(
  kind: Kind,
  name: string,
  options?: FileParseOptions,
): Param<Kind, unknown>;

fileSchema

Added in v4.0.0 Source

Creates a parameter that reads and validates file content using a schema.

Signature

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

fileText

Added in v4.0.0 Source

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

Signature

declare function fileText<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, string>;

float

Added in v4.0.0 Source

Creates a floating-point number parameter.

Signature

declare function float<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, number>;

integer

Added in v4.0.0 Source

Creates an integer parameter.

Signature

declare function integer<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, number>;

keyValuePair

Added in v4.0.0 Source

Creates a param that parses key=value pairs.

When to use

Use when you need command-line options or arguments that collect key=value configuration entries.

Details

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

Signature

declare function keyValuePair<Kind extends ParamKind>(
  kind: Kind,
  name: string,
): Param<Kind, Record<string, string>>;

makeSingle

Added in v4.0.0 Source

Constructs a leaf Single parameter from its kind, name, primitive parser, and optional help metadata.

Details

The returned parser reads either one positional argument or the named flag, depending on kind.

Signature

declare function makeSingle<Kind extends ParamKind, A>(params: {
  readonly aliases?: readonly Array<string>;
  readonly description?: Option<string>;
  readonly hidden?: boolean;
  readonly kind: Kind;
  readonly name: string;
  readonly primitiveType: Primitive<A>;
  readonly typeName?: string;
}): Single<Kind, A>

none

Added in v4.0.0 Source

Creates an empty sentinel parameter that always fails to parse.

When to use

Use when you need an empty CLI parameter sentinel for optional parameter construction or internal combinators.

Signature

declare function none<Kind extends ParamKind>(kind: Kind): Param<Kind, never>;

path

Added in v4.0.0 Source

Creates a path parameter that accepts file or directory paths.

Signature

declare function path<Kind extends ParamKind>(
  kind: Kind,
  name: string,
  options?: {
    readonly mustExist?: boolean;
    readonly pathType?: PathType;
    readonly typeName?: string;
  },
): Param<Kind, string>;

redacted

Added in v4.0.0 Source

Creates a redacted parameter for sensitive data like passwords. The value is masked in help output and logging.

Signature

declare function redacted<Kind extends ParamKind>(
  kind: Kind,
  name: string,
): Param<Kind, Redacted<string>>;

string

Added in v4.0.0 Source

Creates a string parameter.

Signature

declare function string<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, string>;

Guards

isParam

Added in v4.0.0 Source

Type guard to check if a value is a Param.

Signature

declare function isParam(u: unknown): u is Param<any, ParamKind>;

isSingle

Added in v4.0.0 Source

Type guard to check if a param is a Single param (not composed).

Signature

declare function isSingle<Kind extends ParamKind, A>(
  param: Param<Kind, A>,
): param is Single<Kind, A>;

Metadata

withHidden

Added in v4.0.0 Source

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

When to use

Use when experimental, internal, or deprecated flags should be accepted but not advertised.

Signature

declare function withHidden<Kind extends ParamKind, A>(self: Param<Kind, A>): Param<Kind, A>;

withMetavar

Added in v4.0.0 Source

Sets a custom metavar (placeholder name) for the param 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: {
  <K extends ParamKind>(metavar: string): <A>(self: Param<K, A>) => Param<K, A>;
  <K extends ParamKind, A>(self: Param<K, A>, metavar: string): Param<K, A>;
};

Models

Any type

Added in v4.0.0 Source

Represents any parameter.

Signature

type Any = Param<ParamKind, unknown>;

AnyArgument type

Added in v4.0.0 Source

Represents any positional argument parameter.

Signature

type AnyArgument = Param<typeof argumentKind, unknown>;

AnyFlag type

Added in v4.0.0 Source

Represents any flag parameter.

Signature

type AnyFlag = Param<typeof flagKind, unknown>;

FallbackPrompt type

Added in v4.0.0 Source

Represents a fallback prompt that can either be provided directly or computed effectfully when the parameter is missing.

Signature

type FallbackPrompt<A> =
  | Prompt.Prompt<A>
  | Effect.Effect<Prompt.Prompt<A>, CliError.CliError, Environment>;

Flags type

Added in v4.0.0 Source

Map of flag names to their provided string values. Multiple occurrences of a flag produce multiple values.

Signature

type Flags = Record<string, ReadonlyArray<string>>;

Map interface

Added in v4.0.0 Source

Parameter node that maps the successfully parsed value of another parameter with a pure function.

Signature

interface Map<Kind extends ParamKind, in out A, out B> extends Param<Kind, B> {
  readonly _tag: "Map";
  readonly f: (value: A) => B;
  readonly kind: Kind;
  readonly param: Param<Kind, A>;
}

Optional interface

Added in v4.0.0 Source

Parameter node that turns a missing argument or flag into Option.none() and a present parsed value into Option.some(value).

Signature

interface Optional<Kind extends ParamKind, A> extends Param<Kind, Option.Option<A>> {
  readonly _tag: "Optional";
  readonly kind: Kind;
  readonly param: Param<Kind, A>;
}

Param interface

Added in v4.0.0 Source

Polymorphic CLI parameter shared by Argument and Flag.

Details

A parameter knows whether it consumes positional arguments or flags and parses a ParsedArgs value into its typed result.

Signature

interface Param<Kind extends ParamKind, out A> extends Variance<A> {
  readonly _tag: "Single" | "Map" | "Transform" | "Optional" | "Variadic";
  readonly kind: Kind;
  readonly parse: Parse<A>;
}

ParamKind type

Added in v4.0.0 Source

Discriminator for whether a Param parses positional arguments or command-line flags.

Signature

type ParamKind = "argument" | "flag";

Parse type

Added in v4.0.0 Source

Function type used by parameters to parse currently available flags and positional arguments.

Details

It returns the remaining positional arguments together with the parsed value, or fails with a CliError while requiring the CLI parsing environment.

Signature

type Parse<A> = (
  args: ParsedArgs,
) => Effect.Effect<
  readonly [leftover: ReadonlyArray<string>, value: A],
  CliError.CliError,
  Environment
>;

ParsedArgs interface

Added in v4.0.0 Source

Input context passed to Param.parse implementations. - flags: already-collected flag values by canonical flag name - arguments: remaining positional arguments to be consumed

Signature

interface ParsedArgs {
  readonly arguments: readonly Array<string>;
  readonly flags: Flags;
}

Single interface

Added in v4.0.0 Source

Leaf parameter that reads one named argument or flag with a primitive parser.

Details

Single parameters carry the user-facing name, aliases, description, primitive type, and optional metavar/type name used in help output.

Signature

interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
  readonly _tag: "Single";
  readonly aliases: readonly Array<string>;
  readonly description: Option<string>;
  readonly hidden: boolean;
  readonly kind: Kind;
  readonly name: string;
  readonly primitiveType: Primitive<A>;
  readonly typeName?: string;
}

Transform interface

Added in v4.0.0 Source

Parameter node that rewrites another parameter's parser, allowing effectful validation, fallback behavior, or error translation while preserving the same parameter kind.

Signature

interface Transform<Kind extends ParamKind, in out A, out B> extends Param<Kind, B> {
  readonly _tag: "Transform";
  readonly alternatives: readonly Array<LazyArg<Param<Kind, unknown>>>;
  readonly f: (parse: Parse<A>, alternatives: readonly Array<LazyArg<Parse<unknown>>>) => Parse<B>;
  readonly kind: Kind;
  readonly param: Param<Kind, A>;
}

Variadic interface

Added in v4.0.0 Source

Parameter node that parses another parameter zero or more times and returns all parsed values as an array, respecting optional minimum and maximum occurrence bounds.

Signature

interface Variadic<Kind extends ParamKind, A> extends Param<Kind, ReadonlyArray<A>> {
  readonly _tag: "Variadic";
  readonly kind: Kind;
  readonly max: Option<number>;
  readonly min: Option<number>;
  readonly param: Param<Kind, A>;
}

Options

VariadicParamOptions type

Added in v4.0.0 Source

Represent options which can be used to configure variadic parameters.

Signature

type VariadicParamOptions = {
  readonly max?: number;
  readonly min?: number;
};

Other

Param

Added in v4.0.0 Source

Namespace containing type-level utilities attached to the Param interface.