Prompt unstable
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
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>;}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>Example Collecting prompt results
import { Effect, FileSystem, Layer, Path, Terminal } from "effect"import { Prompt } from "effect/cli"
const terminal = Terminal.make({ columns: Effect.succeed(80), rows: Effect.succeed(24), readInput: Effect.succeed({} as never), readLine: Effect.die("unused"), display: () => Effect.void})const services = Layer.mergeAll( FileSystem.layerNoop({}), Path.layer, Layer.succeed(Terminal.Terminal, terminal))
const username = Prompt.succeed("alice")const password = Prompt.succeed("secret")
const allWithTuple = Prompt.all([username, password])
const allWithRecord = Prompt.all({ username, password })
await Effect.runPromise(Effect.provide(allWithTuple, services)) // => ["alice", "secret"]await Effect.runPromise(Effect.provide(allWithRecord, services)) // => { username: "alice", password: "secret" }Constructors
AutoComplete
unstableCreates a prompt that lets users filter select choices by typing.
Details
Every printable character is appended to the filter query, so navigation is
bound to the arrow keys, tab, and the Ctrl+P / Ctrl+N chords used by
readline and fzf (Ctrl+K also moves up). Ctrl+U clears the query.
Signature
declare function AutoComplete<A>(options: AutoCompleteOptions<A>): Prompt<A>Example Filtering choices with autocomplete
import { Prompt } from "effect/cli"
const language = Prompt.AutoComplete({ message: "Choose a language", choices: [ { title: "TypeScript", value: "ts" }, { title: "Rust", value: "rs" }, { title: "Kotlin", value: "kt" } ]})
Prompt.isPrompt(language) // => trueCreates 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 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.
You can also type to filter the listed entries. Every printable character is
appended to the filter query, so navigation is bound to the arrow keys,
tab, and the Ctrl+P / Ctrl+N chords used by readline and fzf
(Ctrl+K also moves up). Ctrl+U clears the query.
Signature
declare function File(options: FileOptions): Prompt<string>Creates a text prompt that does not echo typed input and returns the
submitted value wrapped in Redacted.
Signature
declare function Hidden(options: TextOptions): Prompt<Redacted<string>>Creates an integer prompt.
Details
The prompt supports minimum and maximum bounds, keyboard step sizes, and additional validation before submission.
Signature
declare function Int(options: IntOptions): 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>>Creates a prompt theme using the current platform defaults.
Details
Unless colors is provided, it is detected when the theme is created:
colors are enabled when stdout is a TTY and NO_COLOR is unset or empty.
Signature
declare function makeTheme(options?: Partial<Theme>): ThemeMultiSelect
unstableCreates 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 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 Number(options: NumberOptions): Prompt<number>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 text-entry prompt that echoes input and returns the submitted string after validation.
Signature
declare function String(options: TextOptions): Prompt<string>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 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; };}>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; };}Represents the services available to a custom Prompt.
Signature
type Environment = FileSystem.FileSystem | Path.Path | Terminal.TerminalRepresents 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>;}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>; };}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;}Defines the symbols used to render built-in prompts.
Details
Set a symbol to an empty string to omit both the symbol and its adjacent spacing.
Signature
interface Theme { readonly arrowDown: string; readonly arrowUp: string; readonly checkboxOff: string; readonly checkboxOn: string; readonly colors: boolean; readonly descriptionSeparator: string; readonly ellipsis: string; readonly errorColor: string; readonly mutedColor: string; readonly passwordMask: string; readonly pointer: string; readonly pointerSmall: string; readonly prefix: string; readonly primaryColor: string; readonly submittedColor: string; readonly successColor: string; readonly tick: string; readonly toggleSeparator: string;}Options
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; readonly message: string;}Options for a confirmation prompt that asks the user to choose a boolean yes/no value.
Signature
interface ConfirmOptions extends ThemeOptions { readonly initial?: boolean; readonly label?: { readonly confirm: string; readonly deny: string; }; readonly message: string; readonly placeholder?: { readonly defaultConfirm?: string; readonly defaultDeny?: string; };}Options for a date prompt, including the displayed message, initial value, format mask, validation, and locale labels.
Signature
interface DateOptions extends ThemeOptions { 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>;}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 extends ThemeOptions { readonly default?: string; readonly filter?: (file: string) => boolean | Effect<boolean, never, Environment>; readonly maxPerPage?: number; readonly message?: string; readonly startingPath?: string; readonly type?: PathType;}Options for an integer prompt, including bounds, keyboard step sizes, and additional validation.
Signature
interface IntOptions extends ThemeOptions { 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>;}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;}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;}Options for Number, extending IntOptions with display precision.
Signature
interface NumberOptions extends IntOptions { readonly precision?: number;}Options for a prompt that asks the user to select one value from a list of choices.
Signature
interface SelectOptions<A> extends ThemeOptions { readonly choices: readonly Array<SelectChoice<A>>; readonly maxPerPage?: number; readonly message?: string;}Options for text-entry prompts, including the displayed message, default text, and effectful validation before submission.
Signature
interface TextOptions extends ThemeOptions { readonly default?: string; readonly message: string; readonly validate?: (value: string) => Effect<string, string>;}Options shared by built-in prompts that support theme overrides.
Signature
interface ThemeOptions { readonly theme?: Partial<Theme>;}Options for a toggle prompt that lets the user switch between active and inactive boolean states.
Signature
interface ToggleOptions extends ThemeOptions { 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>Services
Context reference for the theme used by built-in prompts.
Details
Provide this reference once to theme every prompt in an application. A
prompt's theme option takes precedence over the context value. The
command wizard also reads colors from this reference, so provide a theme
with colors: false to disable wizard styling.
The default value is created with makeTheme the first time it is read,
so color detection runs once per process. Changes to NO_COLOR after the
first prompt do not affect the default theme.
Signature
declare const Theme: Reference<Theme>