Prompt
Builds interactive terminal prompts for CLI applications.
A Prompt<A> describes a small terminal UI that renders frames, reads keyboard input, validates responses, and eventually produces an A. Prompts can ask for simple values, selections, lists, files, hidden text, or custom interactions. This module includes prompt constructors, tools for combining and transforming prompt output, and support for running prompts through the Terminal service.
Combinators
Signature
declare const flatMap: {
<Output, Output2>(
f: (output: Output) => Prompt<Output2>,
): (self: Prompt<Output>) => Prompt<Output2>;
<Output, Output2>(self: Prompt<Output>, f: (output: Output) => Prompt<Output2>): Prompt<Output2>;
};Transforms the output value produced by a prompt.
Signature
declare const map: {
<Output, Output2>(f: (output: Output) => Output2): (self: Prompt<Output>) => Prompt<Output2>;
<Output, Output2>(self: Prompt<Output>, f: (output: Output) => Output2): Prompt<Output2>;
};Combining
Runs all the provided prompts in sequence respecting the structure provided in input.
Details
Supports either a tuple / iterable of prompts or a record / struct of prompts as an argument.
Signature
declare const all: <Arg extends Iterable<Prompt<any>> | Record<string, Prompt<any>>>(
arg: Arg,
) => All.Return<Arg>;Constructors
autoComplete
Creates a prompt that lets users filter select choices by typing.
Signature
declare function autoComplete<A>(options: AutoCompleteOptions<A>): Prompt<A>;Creates a confirmation prompt that asks the user to choose a boolean yes/no value.
When to use
Use to ask for a yes/no answer that can be submitted directly.
Details
initial defaults to false. Enter submits the current default, yes-style input submits true, no-style input submits false, and other input beeps.
See
togglefor an interactive switch-before-submit boolean prompt
Signature
declare function confirm(options: ConfirmOptions): Prompt<boolean>;Creates a custom Prompt from the specified initial state and handlers.
Details
The initial state can either be a pure value or an Effect. This is particularly useful when the initial state of the Prompt must be computed by performing an effectful computation, such as reading data from the file system. A Prompt runs as a render loop: render returns ANSI output for the current frame, the Terminal obtains user input, process returns the next prompt action, and clear returns ANSI output used to clear the previous frame.
Optionally, an external events dequeue can be provided as the third argument. When present, the render loop will race user input against events from the dequeue, allowing background events to trigger re-renders without waiting for a keypress. When an event is received from the dequeue, the receive handler is called instead of process.
Signature
declare const custom: {
<State, Output>(
initialState: State | Effect<State, never, Environment>,
handlers: Handlers<State, Output>,
): Prompt<Output>;
<State, Output, A>(
initialState: State | Effect<State, never, Environment>,
events: Dequeue<A, never>,
handlers: Handlers<
State,
Output,
| {
readonly _tag: Tag;
readonly input: Terminal.UserInput;
}
| {
readonly _tag: Tag;
readonly value: A;
}
>,
): Prompt<Output>;
};Creates a date prompt that lets the user edit a formatted date value and validates the final Date before submission.
Details
initial defaults to the current Date, dateMask defaults to YYYY-MM-DD HH:mm:ss, mask parsing creates editable date parts plus literal tokens, locales customizes month and weekday labels, and validate runs on submission.
Gotchas
A supplied initial Date is edited in place during prompt interaction. Date edits use JavaScript Date setters, so out-of-range typed values can normalize before validation. If the prompt is meant to be editable, dateMask should contain at least one editable date token.
Signature
declare function date(options: DateOptions): Prompt<Date>;Creates a file-system selection prompt and returns the selected path.
Details
The prompt can be configured to select files, directories, or either path type.
Signature
declare function file(options: FileOptions): Prompt<string>;Creates a floating-point number prompt.
Details
The prompt supports minimum and maximum bounds, keyboard step sizes, display precision, and additional validation before submission.
Signature
declare function float(options: FloatOptions): Prompt<number>;Creates an integer prompt.
Details
The prompt supports minimum and maximum bounds, keyboard step sizes, and additional validation before submission.
Signature
declare function integer(options: IntegerOptions): Prompt<number>;Creates a text prompt that returns an array of strings by splitting the submitted input on the configured delimiter.
Signature
declare function list(options: ListOptions): Prompt<Array<string>>;multiSelect
Creates a prompt that lets the user select multiple choices and returns their values as an array.
Details
The prompt supports default selected choices, bulk-selection commands, and minimum or maximum selection counts.
Signature
declare function multiSelect<A>(options: SelectOptions<A> & MultiSelectOptions): Prompt<Array<A>>;Creates a password prompt that masks typed input and returns the submitted value wrapped in Redacted.
Signature
declare function password(options: TextOptions): Prompt<Redacted<string>>;Creates a prompt that lets the user select a single value from a list of choices.
Gotchas
At most one choice may be marked as selected by default.
Signature
declare function select<A>(options: SelectOptions<A>): Prompt<A>;Creates a Prompt which immediately succeeds with the specified value.
Details
This prompt does not attempt to obtain user input or render anything to the screen.
Signature
declare function succeed<A>(value: A): Prompt<A>;Creates a text-entry prompt that echoes input and returns the submitted string after validation.
Signature
declare function text(options: TextOptions): Prompt<string>;Creates a toggle prompt that lets the user switch between active and inactive states and returns the selected boolean value.
Signature
declare function toggle(options: ToggleOptions): Prompt<boolean>;Guards
Models
Represents the action that should be taken by a Prompt based upon user input or an external event received during the current frame.
Signature
type Action<State, Output> = Data.TaggedEnum<{
readonly Beep: {};
readonly NextFrame: {
readonly state: State;
};
readonly Submit: {
readonly value: Output;
};
}>;ActionDefinition interface
Type-level definition for the tagged Prompt.Action variants.
Details
It connects the action state and output type parameters to the Beep, NextFrame, and Submit action cases.
Signature
interface ActionDefinition extends WithGenerics<2> {
readonly taggedEnum:
| {
readonly _tag: "Beep";
}
| {
readonly _tag: "NextFrame";
readonly state: unknown;
}
| {
readonly _tag: "Submit";
readonly value: unknown;
};
}Environment type
Represents the services available to a custom Prompt.
Signature
type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal;Represents the set of handlers used by a Prompt.
Details
The handlers render the current frame, process user input into the next Prompt.Action, and clear the terminal screen before the next frame.
Signature
interface Handlers<State, Output, Input = Terminal.UserInput> {
readonly clear: (
state: State,
action:
| {
readonly _tag: "Beep";
}
| {
readonly _tag: "NextFrame";
readonly state: State;
}
| {
readonly _tag: "Submit";
readonly value: Output;
},
) => Effect<string, never, Environment>;
readonly process: (
input: Input,
state: State,
) => Effect<
| {
readonly _tag: "Beep";
}
| {
readonly _tag: "NextFrame";
readonly state: State;
}
| {
readonly _tag: "Submit";
readonly value: Output;
},
never,
Environment
>;
readonly render: (
state: State,
action:
| {
readonly _tag: "Beep";
}
| {
readonly _tag: "NextFrame";
readonly state: State;
}
| {
readonly _tag: "Submit";
readonly value: Output;
},
) => Effect<string, never, Environment>;
}ProcessInput type
Represents the input that should be processed by a Prompt based upon user input or an external event received during the current frame.
Signature
type ProcessInput<A> = Data.TaggedEnum<{
readonly Event: {
readonly value: A;
};
readonly Input: {
readonly input: Terminal.UserInput;
};
}>;Represents an interactive terminal prompt that produces an Output value.
Details
A Prompt is an Effect that may fail with Terminal.QuitError and requires the prompt environment needed to render frames, read input, and access files or paths when a prompt uses them.
Signature
interface Prompt<Output> extends Effect<Output, Terminal.QuitError, Environment> {
readonly "~effect/cli/Prompt": {
readonly _Output: Covariant<Output>;
};
}SelectChoice interface
Represents one choice displayed by select, autocomplete, and multi-select prompts.
Signature
interface SelectChoice<A> {
readonly description?: string;
readonly disabled?: boolean;
readonly selected?: boolean;
readonly title: string;
readonly value: A;
}Options
AutoCompleteOptions interface
Options for an autocomplete prompt that lets the user filter selectable choices by typing.
Signature
interface AutoCompleteOptions<A> extends SelectOptions<A> {
readonly emptyMessage?: string;
readonly filterLabel?: string;
readonly filterPlaceholder?: string;
}ConfirmOptions interface
Options for a confirmation prompt that asks the user to choose a boolean yes/no value.
Signature
interface ConfirmOptions {
readonly initial?: boolean;
readonly label?: {
readonly confirm: string;
readonly deny: string;
};
readonly message: string;
readonly placeholder?: {
readonly defaultConfirm?: string;
readonly defaultDeny?: string;
};
}DateOptions interface
Options for a date prompt, including the displayed message, initial value, format mask, validation, and locale labels.
Signature
interface DateOptions {
readonly dateMask?: string;
readonly initial?: Date;
readonly locales?: {
readonly months: [
string,
string,
string,
string,
string,
string,
string,
string,
string,
string,
string,
string,
];
readonly monthsShort: [
string,
string,
string,
string,
string,
string,
string,
string,
string,
string,
string,
string,
];
readonly weekdays: [string, string, string, string, string, string, string];
readonly weekdaysShort: [string, string, string, string, string, string, string];
};
readonly message: string;
readonly validate?: (value: Date) => Effect<Date, string>;
}FileOptions interface
Options for a file-system selection prompt.
Details
They control which path type can be selected, the starting directory, paging, and filtering of displayed entries.
Signature
interface FileOptions {
readonly default?: string;
readonly filter?: (file: string) => boolean | Effect<boolean, never, Environment>;
readonly maxPerPage?: number;
readonly message?: string;
readonly startingPath?: string;
readonly type?: PathType;
}FloatOptions interface
Options for a floating-point number prompt.
Details
In addition to the numeric bounds and step settings from IntegerOptions, the prompt can be configured with a display precision.
Signature
interface FloatOptions extends IntegerOptions {
readonly precision?: number;
}IntegerOptions interface
Options for an integer prompt, including bounds, keyboard step sizes, and additional validation.
Signature
interface IntegerOptions {
readonly decrementBy?: number;
readonly default?: number;
readonly incrementBy?: number;
readonly max?: number;
readonly message: string;
readonly min?: number;
readonly validate?: (value: number) => Effect<number, string>;
}ListOptions interface
Options for a text prompt that returns a list of strings by splitting the input on a delimiter.
Signature
interface ListOptions extends TextOptions {
readonly delimiter?: string;
}MultiSelectOptions interface
Options for a multi-select prompt, including bulk-selection labels and minimum or maximum selection counts.
Signature
interface MultiSelectOptions {
readonly inverseSelection?: string;
readonly max?: number;
readonly min?: number;
readonly selectAll?: string;
readonly selectNone?: string;
}SelectOptions interface
Options for a prompt that asks the user to select one value from a list of choices.
Signature
interface SelectOptions<A> {
readonly choices: readonly Array<SelectChoice<A>>;
readonly maxPerPage?: number;
readonly message: string;
}TextOptions interface
Options for text-entry prompts, including the displayed message, default text, and effectful validation before submission.
Signature
interface TextOptions {
readonly default?: string;
readonly message: string;
readonly validate?: (value: string) => Effect<string, string>;
}ToggleOptions interface
Options for a toggle prompt that lets the user switch between active and inactive boolean states.
Signature
interface ToggleOptions {
readonly active?: string;
readonly inactive?: string;
readonly initial?: boolean;
readonly message: string;
}Other
Running
Runs a prompt by reading terminal input and rendering prompt frames until the prompt submits a value.
Gotchas
The returned effect may fail with Terminal.QuitError if terminal input ends or the prompt is quit.
Signature
declare const run: <Output>(
self: Prompt<Output>,
) => Effect.Effect<Output, Terminal.QuitError, Environment>;
Composes prompts by using the output of this prompt to create the next prompt.