Skip to content

Prompt.ts

Prompt.ts overview

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.

Since v4.0.0

Exports Grouped by Category

collecting & elements
- all
combinators
- flatMap
- map
constructors
- autoComplete
- confirm
- custom
- date
- file
- float
- hidden
- integer
- list
- multiSelect
- password
- select
- succeed
- text
- toggle
execution
- run
guards
- isPrompt
models
options
utility types
- Any (type alias)
utils
- All (namespace)

collecting & elements

all

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.

Example (Collecting prompt results)

import { Effect } from "effect"
import { Prompt } from "effect/unstable/cli"

const username = Prompt.text({
  message: "Enter your username: "
})

const password = Prompt.password({
  message: "Enter your password: ",
  validate: (value) => (value.length === 0 ? Effect.fail("Password cannot be empty") : Effect.succeed(value))
})

const allWithTuple = Prompt.all([username, password])

const allWithRecord = Prompt.all({ username, password })

Signature

declare const all: <const Arg extends Iterable<Prompt<any>> | Record<string, Prompt<any>>>(arg: Arg) => All.Return<Arg>

Since v4.0.0

combinators

flatMap

Composes prompts by using the output of this prompt to create the next prompt.

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>
}

Since v4.0.0

map

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>
}

Since v4.0.0

constructors

autoComplete

Creates a prompt that lets users filter select choices by typing.

Example (Filtering choices with autocomplete)

import { Prompt } from "effect/unstable/cli"

const language = Prompt.autoComplete({
  message: "Choose a language",
  choices: [
    { title: "TypeScript", value: "ts" },
    { title: "Rust", value: "rs" },
    { title: "Kotlin", value: "kt" }
  ]
})

Signature

declare const autoComplete: <const A>(options: AutoCompleteOptions<A>) => Prompt<A>

Since v4.0.0

confirm

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

toggle for an interactive switch-before-submit boolean prompt

Signature

declare const confirm: (options: ConfirmOptions) => Prompt<boolean>

Since v4.0.0

custom

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.Effect<State, never, Environment>,
    handlers: Handlers<State, Output>
  ): Prompt<Output>
  <State, Output, A>(
    initialState: State | Effect.Effect<State, never, Environment>,
    events: Queue.Dequeue<A, never>,
    handlers: Handlers<State, Output, ProcessInput<A>>
  ): Prompt<Output>
}

Since v4.0.0

date

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 const date: (options: DateOptions) => Prompt<Date>

Since v4.0.0

file

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 const file: (options?: FileOptions) => Prompt<string>

Since v4.0.0

float

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 const float: (options: FloatOptions) => Prompt<number>

Since v4.0.0

hidden

Creates a text prompt that does not echo typed input and returns the submitted value wrapped in Redacted.

Signature

declare const hidden: (options: TextOptions) => Prompt<Redacted.Redacted>

Since v4.0.0

integer

Creates an integer prompt.

Details

The prompt supports minimum and maximum bounds, keyboard step sizes, and additional validation before submission.

Signature

declare const integer: (options: IntegerOptions) => Prompt<number>

Since v4.0.0

list

Creates a text prompt that returns an array of strings by splitting the submitted input on the configured delimiter.

Signature

declare const list: (options: ListOptions) => Prompt<Array<string>>

Since v4.0.0

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 const multiSelect: <const A>(options: SelectOptions<A> & MultiSelectOptions) => Prompt<Array<A>>

Since v4.0.0

password

Creates a password prompt that masks typed input and returns the submitted value wrapped in Redacted.

Signature

declare const password: (options: TextOptions) => Prompt<Redacted.Redacted>

Since v4.0.0

select

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 const select: <const A>(options: SelectOptions<A>) => Prompt<A>

Since v4.0.0

succeed

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 const succeed: <A>(value: A) => Prompt<A>

Since v4.0.0

text

Creates a text-entry prompt that echoes input and returns the submitted string after validation.

Signature

declare const text: (options: TextOptions) => Prompt<string>

Since v4.0.0

toggle

Creates a toggle prompt that lets the user switch between active and inactive states and returns the selected boolean value.

Signature

declare const toggle: (options: ToggleOptions) => Prompt<boolean>

Since v4.0.0

execution

run

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>

Since v4.0.0

guards

isPrompt

Returns true if the provided value is a Prompt.

Signature

declare const isPrompt: (u: unknown) => u is Prompt<unknown>

Since v4.0.0

models

Action (type alias)

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 { readonly _tag: "Beep"; } | { readonly _tag: "NextFrame"; readonly state: State; } | { readonly _tag: "Submit"; readonly value: Output; } = Data.TaggedEnum<{
  readonly Beep: {}
  readonly NextFrame: { readonly state: State }
  readonly Submit: { readonly value: Output }
}>

Since v4.0.0

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

export interface ActionDefinition extends Data.TaggedEnum.WithGenerics<2> {
  readonly taggedEnum: Action<this["A"], this["B"]>
}

Since v4.0.0

Environment (type alias)

Represents the services available to a custom Prompt.

Signature

type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal

Since v4.0.0

Handlers (interface)

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

export interface Handlers<State, Output, Input = Terminal.UserInput> {
  /**
   * A function that is called to render the current frame of the `Prompt`.
   */
  readonly render: (state: State, action: Action<State, Output>) => Effect.Effect<string, never, Environment>
  /**
   * A function that is called to process user input and determine the next
   * `Prompt.Action` that should be taken.
   */
  readonly process: (input: Input, state: State) => Effect.Effect<Action<State, Output>, never, Environment>
  /**
   * A function that is called to clear the terminal screen before rendering
   * the next frame of the `Prompt`.
   */
  readonly clear: (state: State, action: Action<State, Output>) => Effect.Effect<string, never, Environment>
}

Since v4.0.0

ProcessInput (type alias)

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 { readonly _tag: "Event"; readonly value: A; } | { readonly _tag: "Input"; readonly input: Terminal.UserInput; } = Data.TaggedEnum<{
  readonly Input: { readonly input: Terminal.UserInput }
  readonly Event: { readonly value: A }
}>

Since v4.0.0

Prompt (interface)

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

export interface Prompt<Output> extends Effect.Effect<Output, Terminal.QuitError, Environment> {
  readonly [TypeId]: {
    readonly _Output: Covariant<Output>
  }
}

Since v4.0.0

SelectChoice (interface)

Represents one choice displayed by select, autocomplete, and multi-select prompts.

Signature

export interface SelectChoice<A> {
  /**
   * The name of the select option that is displayed to the user.
   */
  readonly title: string
  /**
   * The underlying value of the select option.
   */
  readonly value: A
  /**
   * An optional description for the select option which will be displayed
   * to the user.
   */
  readonly description?: string
  /**
   * Whether or not this select option is disabled.
   */
  readonly disabled?: boolean
  /**
   * Whether this option should be selected by default (only used by MultiSelect).
   */
  readonly selected?: boolean
}

Since v4.0.0

options

AutoCompleteOptions (interface)

Options for an autocomplete prompt that lets the user filter selectable choices by typing.

Signature

export interface AutoCompleteOptions<A> extends SelectOptions<A> {
  /**
   * The label used for the filter display (defaults to "filter").
   */
  readonly filterLabel?: string
  /**
   * The placeholder shown when the filter is empty (defaults to "type to filter").
   */
  readonly filterPlaceholder?: string
  /**
   * The message displayed when no choices match (defaults to "No matches").
   */
  readonly emptyMessage?: string
}

Since v4.0.0

ConfirmOptions (interface)

Options for a confirmation prompt that asks the user to choose a boolean yes/no value.

Signature

export interface ConfirmOptions {
  /**
   * The message to display in the prompt.
   */
  readonly message: string
  /**
   * The initial value of the confirm prompt (defaults to `false`).
   */
  readonly initial?: boolean
  /**
   * The label to display after a user has responded to the prompt.
   */
  readonly label?: {
    /**
     * The label used if the prompt is confirmed (defaults to `"yes"`).
     */
    readonly confirm: string
    /**
     * The label used if the prompt is not confirmed (defaults to `"no"`).
     */
    readonly deny: string
  }
  /**
   * The placeholder to display when a user is responding to the prompt.
   */
  readonly placeholder?: {
    /**
     * The placeholder to use if the `initial` value of the prompt is `true`
     * (defaults to `"(Y/n)"`).
     */
    readonly defaultConfirm?: string
    /**
     * The placeholder to use if the `initial` value of the prompt is `false`
     * (defaults to `"(y/N)"`).
     */
    readonly defaultDeny?: string
  }
}

Since v4.0.0

DateOptions (interface)

Options for a date prompt, including the displayed message, initial value, format mask, validation, and locale labels.

Signature

export interface DateOptions {
  /**
   * The message to display in the prompt.
   */
  readonly message: string
  /**
   * The initial date value to display in the prompt (defaults to the current
   * date).
   */
  readonly initial?: globalThis.Date
  /**
   * The format mask of the date (defaults to `YYYY-MM-DD HH:mm:ss`).
   */
  readonly dateMask?: string
  /**
   * An effectful function that can be used to validate the value entered into
   * the prompt before final submission.
   */
  readonly validate?: (value: globalThis.Date) => Effect.Effect<globalThis.Date, string>
  /**
   * Custom locales that can be used in place of the defaults.
   */
  readonly locales?: {
    /**
     * The full names of each month of the year.
     */
    readonly months: [string, string, string, string, string, string, string, string, string, string, string, string]
    /**
     * The short names of each month of the year.
     */
    readonly monthsShort: [
      string,
      string,
      string,
      string,
      string,
      string,
      string,
      string,
      string,
      string,
      string,
      string
    ]
    /**
     * The full names of each day of the week.
     */
    readonly weekdays: [string, string, string, string, string, string, string]
    /**
     * The short names of each day of the week.
     */
    readonly weekdaysShort: [string, string, string, string, string, string, string]
  }
}

Since v4.0.0

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

export interface FileOptions {
  /**
   * The path type that will be selected, defaulting to `"file"`.
   */
  readonly type?: Primitive.PathType
  /**
   * The message to display in the prompt, defaulting to `"Choose a file"`.
   */
  readonly message?: string
  /**
   * Where the user will initially be prompted to select files from, defaulting
   * to the current working directory.
   */
  readonly startingPath?: string
  /**
   * The default path to select when the prompt is first displayed.
   */
  readonly default?: string
  /**
   * The number of choices to display at one time, defaulting to `10`.
   */
  readonly maxPerPage?: number
  /**
   * A predicate or effect that keeps a file in the prompt when it returns
   * `true`, defaulting to returning all files.
   */
  readonly filter?: (file: string) => boolean | Effect.Effect<boolean, never, Environment>
}

Since v4.0.0

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

export interface FloatOptions extends IntegerOptions {
  /**
   * The precision to use for the floating point value (defaults to `2`).
   */
  readonly precision?: number
}

Since v4.0.0

IntegerOptions (interface)

Options for an integer prompt, including bounds, keyboard step sizes, and additional validation.

Signature

export interface IntegerOptions {
  /**
   * The message to display in the prompt.
   */
  readonly message: string
  /**
   * The default value of the integer prompt.
   */
  readonly default?: number
  /**
   * The minimum value that can be entered by the user (defaults to `-Infinity`).
   */
  readonly min?: number
  /**
   * The maximum value that can be entered by the user (defaults to `Infinity`).
   */
  readonly max?: number
  /**
   * The value that will be used to increment the prompt value when using the
   * up arrow key (defaults to `1`).
   */
  readonly incrementBy?: number
  /**
   * The value that will be used to decrement the prompt value when using the
   * down arrow key (defaults to `1`).
   */
  readonly decrementBy?: number
  /**
   * An effectful function that can be used to validate the value entered into
   * the prompt before final submission.
   */
  readonly validate?: (value: number) => Effect.Effect<number, string>
}

Since v4.0.0

ListOptions (interface)

Options for a text prompt that returns a list of strings by splitting the input on a delimiter.

Signature

export interface ListOptions extends TextOptions {
  /**
   * The delimiter that separates list entries.
   */
  readonly delimiter?: string
}

Since v4.0.0

MultiSelectOptions (interface)

Options for a multi-select prompt, including bulk-selection labels and minimum or maximum selection counts.

Signature

export interface MultiSelectOptions {
  /**
   * Text for the "Select All" option (defaults to "Select All").
   */
  readonly selectAll?: string
  /**
   * Text for the "Select None" option (defaults to "Select None").
   */
  readonly selectNone?: string
  /**
   * Text for the "Inverse Selection" option (defaults to "Inverse Selection").
   */
  readonly inverseSelection?: string
  /**
   * The minimum number of choices that must be selected.
   */
  readonly min?: number
  /**
   * The maximum number of choices that can be selected.
   */
  readonly max?: number
}

Since v4.0.0

SelectOptions (interface)

Options for a prompt that asks the user to select one value from a list of choices.

Signature

export interface SelectOptions<A> {
  /**
   * The message to display in the prompt.
   */
  readonly message: string
  /**
   * The choices to display to the user.
   */
  readonly choices: ReadonlyArray<SelectChoice<A>>
  /**
   * The number of choices to display at one time (defaults to `10`).
   */
  readonly maxPerPage?: number
}

Since v4.0.0

TextOptions (interface)

Options for text-entry prompts, including the displayed message, default text, and effectful validation before submission.

Signature

export interface TextOptions {
  /**
   * The message to display in the prompt.
   */
  readonly message: string
  /**
   * The default value of the text option.
   */
  readonly default?: string
  /**
   * An effectful function that can be used to validate the value entered into
   * the prompt before final submission.
   */
  readonly validate?: (value: string) => Effect.Effect<string, string>
}

Since v4.0.0

ToggleOptions (interface)

Options for a toggle prompt that lets the user switch between active and inactive boolean states.

Signature

export interface ToggleOptions {
  /**
   * The message to display in the prompt.
   */
  readonly message: string
  /**
   * The intitial value of the toggle prompt (defaults to `false`).
   */
  readonly initial?: boolean
  /**
   * The text to display when the toggle is in the active state (defaults to
   * `on`).
   */
  readonly active?: string
  /**
   * The text to display when the toggle is in the inactive state (defaults to
   * `off`).
   */
  readonly inactive?: string
}

Since v4.0.0

utility types

Any (type alias)

Type alias for any Prompt, regardless of its output type.

Signature

type Any = Prompt<unknown>

Since v4.0.0

utils

All (namespace)

Namespace containing return-type helpers for Prompt.all.

Since v4.0.0

ReturnIterable (type alias)

Computes the prompt returned by Prompt.all for an iterable of prompts.

Details

The resulting prompt produces an array of each prompt’s output value.

Signature

type ReturnIterable<T> = [T] extends [Iterable<Prompt<infer A>>] ? Prompt<Array<A>> : never

Since v4.0.0

ReturnTuple (type alias)

Computes the prompt returned by Prompt.all for a readonly tuple or array of prompts, preserving tuple positions in the output type.

Signature

type Prompt<T[number] extends never ? [] : { -readonly [K in keyof T]: [T[K]] extends [Prompt<infer _A>] ? _A : never; }> = Prompt<
    T[number] extends never ? []
      : { -readonly [K in keyof T]: [T[K]] extends [Prompt<infer _A>] ? _A : never }
  > extends infer X ? X : never

Since v4.0.0

ReturnObject (type alias)

Computes the prompt returned by Prompt.all for a record of prompts, preserving the record keys and replacing each prompt with its output type.

Signature

type ReturnObject<T> = [T] extends [{ [K: string]: Any }]
  ? Prompt<{
      -readonly [K in keyof T]: [T[K]] extends [Prompt<infer _A>] ? _A : never
    }>
  : never

Since v4.0.0

Return (type alias)

Computes the return prompt type for Prompt.all based on the input structure.

Signature

type Return<Arg> = [Arg] extends [ReadonlyArray<Any>]
  ? ReturnTuple<Arg>
  : [Arg] extends [Iterable<Any>]
    ? ReturnIterable<Arg>
    : [Arg] extends [Record<string, Any>]
      ? ReturnObject<Arg>
      : never

Since v4.0.0