Argument

Defines typed positional arguments for Effect CLI applications.

Arguments consume ordered values after a command name and its flags, then parse them into the types a command handler expects. This module includes constructors for common argument shapes, plus helpers for optional or variadic arguments, schema validation, transformations, defaults, config fallbacks, and prompts for missing values.

33 exports Added in v4.0.0 Source

Combinators

atLeast

Added in v4.0.0 Source

Creates a variadic argument that requires at least n values.

Signature

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

atMost

Added in v4.0.0 Source

Creates a variadic argument that accepts at most n values.

Signature

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

between

Added in v4.0.0 Source

Creates a variadic argument that accepts between min and max values.

Signature

declare const between: {
  <A>(min: number, max: number): (self: Argument<A>) => Argument<readonly Array<A>>;
  <A>(self: Argument<A>, min: number, max: number): Argument<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: (a: A) => boolean, onFalse: (a: A) => string): (self: Argument<A>) => Argument<A>;
  <A>(self: Argument<A>, predicate: (a: A) => boolean, onFalse: (a: A) => string): Argument<A>;
};

filterMap

Added in v4.0.0 Source

Filters and transforms parsed values, failing with a custom error message if the filter function returns None.

Signature

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

map

Added in v4.0.0 Source

Transforms the parsed value of a positional argument.

Signature

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

mapEffect

Added in v4.0.0 Source

Transforms the parsed value of a positional argument using an effectful function.

Signature

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

mapTryCatch

Added in v4.0.0 Source

Transforms the parsed value of a positional argument using a function that may throw.

Signature

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

optional

Added in v4.0.0 Source

Makes a positional argument optional.

Signature

declare function optional<A>(arg: Argument<A>): Argument<Option<A>>;

orElse

Added in v4.0.0 Source

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

Signature

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

orElseResult

Added in v4.0.0 Source

Provides a fallback argument, wrapping results in Result to distinguish which succeeded.

Signature

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

variadic

Added in v4.0.0 Source

Creates a variadic positional argument that accepts multiple values.

Signature

declare const variadic: {
  (options?: VariadicParamOptions): <A>(self: Argument<A>) => Argument<readonly Array<A>>;
  <A>(self: Argument<A>, options?: VariadicParamOptions): Argument<readonly Array<A>>;
}

withDefault

Added in v4.0.0 Source

Provides a default value for a positional argument.

Signature

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

withDescription

Added in v4.0.0 Source

Adds a description to a positional argument.

Signature

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

withFallbackConfig

Added in v4.0.0 Source

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

Signature

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

withFallbackPrompt

Added in v4.0.0 Source

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

Signature

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

withSchema

Added in v4.0.0 Source

Validates parsed values against a Schema.

Signature

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

Constructors

choice

Added in v4.0.0 Source

Creates a positional choice argument.

Signature

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

choiceWithValue

Added in v4.0.0 Source

Creates a positional choice argument with custom value mapping.

Signature

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

date

Added in v4.0.0 Source

Creates a positional date argument.

Signature

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

file

Added in v4.0.0 Source

Creates a positional file path argument.

Signature

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

fileParse

Added in v4.0.0 Source

Creates a positional argument that reads a file and parses its content.

Details

The parser is chosen from the explicit format option or, when omitted, the file extension. The parsed value is unknown; use fileSchema when the parsed content should also be decoded with a Schema.

Signature

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

fileSchema

Added in v4.0.0 Source

Creates a positional argument that reads and validates file content using a schema.

Signature

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

fileText

Added in v4.0.0 Source

Creates a positional argument that reads file content as a string.

Signature

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

float

Added in v4.0.0 Source

Creates a positional float argument.

Signature

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

integer

Added in v4.0.0 Source

Creates a positional integer argument.

Signature

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

none

Added in v4.0.0 Source

Creates an empty sentinel argument that always fails to parse.

Signature

declare const none: Argument<never>;

path

Added in v4.0.0 Source

Creates a positional path argument.

Signature

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

redacted

Added in v4.0.0 Source

Creates a positional redacted argument that obscures its value.

Signature

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

string

Added in v4.0.0 Source

Creates a positional string argument.

Signature

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

Metadata

withMetavar

Added in v4.0.0 Source

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

Details

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

Signature

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

Models

Argument interface

Added in v4.0.0 Source

Represents a positional command-line argument.

Gotchas

boolean is intentionally omitted from Argument constructors. Positional boolean arguments are ambiguous in CLI design since there is no flag name to negate (for example, --no-verbose). Use Flag.boolean instead, or use Argument.choice with explicit "true" / "false" strings if needed.

Signature

interface Argument<A> extends Param<typeof Param.argumentKind, A> {}