https://github.com/topcli/prompts
Node.js user prompt library for command-line interfaces.
https://github.com/topcli/prompts
cli nodejs prompt prompts
Last synced: 2 months ago
JSON representation
Node.js user prompt library for command-line interfaces.
- Host: GitHub
- URL: https://github.com/topcli/prompts
- Owner: TopCli
- License: isc
- Created: 2023-03-05T20:53:52.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-08-01T12:06:10.000Z (11 months ago)
- Last Synced: 2025-08-01T14:36:50.929Z (11 months ago)
- Topics: cli, nodejs, prompt, prompts
- Language: TypeScript
- Homepage:
- Size: 566 KB
- Stars: 32
- Watchers: 3
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
[](https://github.com/TopCli/prompts/commit-activity)
[](https://github.com/TopCli/prompts/blob/main/LICENSE)
[](https://ossf.github.io/scorecard-visualizer/#/projects/github.com/TopCli/prompts)
## Requirements
- [Node.js](https://nodejs.org/en/) v22 or higher
## Getting Started
This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
```bash
$ npm i @topcli/prompts
# or
$ yarn add @topcli/prompts
```
## Usage exemple
You can locally run `node ./demo.js`
```js
import { question, confirm, select, multiselect } from "@topcli/prompts";
const kTestRunner = ["node", "tap", "tape", "vitest", "mocha", "ava"];
const name = await question("Project name ?", { defaultValue: "foo" });
const runner = await select("Choose a test runner", { choices: kTestRunner, maxVisible: 5 });
const isCLI = await confirm("Your project is a CLI ?", { initial: true });
const os = await multiselect("Choose OS", {
choices: ["linux", "mac", "windows"],
preSelectedChoices: ["linux"]
});
console.log(name, runner, isCLI, os);
```
## API
### `question()`
```ts
question(message: string, options?: QuestionOptions): Promise
```
Simple prompt, similar to `rl.question()` with an improved UI.
Use `options.defaultValue` to set a default value.
Use `options.hint` to display a hint alongside the question.
Use `options.secure` if you need to hide both input and answer. You can provide either a **boolean** or an **object** which allows to configure a `placeholder` such as `*`.
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
Use `options.validators` to validate user input and re-prompt on failure.
Use `options.transformer` to parse and validate user input in a single step, returning a typed value. **Mutually exclusive with `validators`.**
Use `options.skip` to skip prompt. It will return `options.defaultValue` if given, `""` otherwise.
**Validators examples**
```js
const packageName = await question('Package name', {
validators: [
{
validate: (value) => {
if (fs.existsSync(path.join(process.cwd(), value))) {
return `Folder ${value} already exists`;
}
}
}
]
});
```
Validators can also be async, for example to validate against an API:
```js
const userId = await question('User ID', {
validators: [
{
validate: async(userId) => {
const res = await fetch(`https://api.com/users/${userId}`);
if (!res.ok) {
return {
isValid: false,
error: `User '${userId}' not found`
}
}
}
}
]
});
```
**Transformers examples**
```js
import { question, transformers } from "@topcli/prompts";
const port = await question("Port", { transformer: transformers.number() });
```
Custom transformer:
```js
const date = await question("Choose date (YYYY-MM-DD)", {
transformer: {
transform: (input) => {
const date = new Date(input);
if (isNaN(date.getTime())) {
return { isValid: false, error: "invalid date" };
}
return { isValid: true, transformed: date };
}
}
});
```
**Built-in validators**
- `validators.required()` : rejects empty input
```js
import { question, validators } from "@topcli/prompts";
const name = await question("What's your name ?", {
validators: [validators.required()]
});
```
**Built-in transformers**
- `transformers.number()`: parses input as a number, rejects non-numeric and empty strings
- `transformers.integer()`: parses input as an integer, rejects floats, non-numeric and empty strings
- `transformers.url()`: parses input as a `URL` object, rejects invalid URLs
```js
import { question, transformers } from "@topcli/prompts";
const count = await question("Count", { transformer: transformers.integer() });
const url = await question("Url", { transformer: transformers.url() });
```
### `select()`
```ts
select(message: string, options: SelectOptions): Promise
```
Scrollable select depending `maxVisible` (default `8`).
Use `options.ignoreValues` to skip result render & clear lines after a selected one.
Use `options.validators` to handle user input.
Use `options.autocomplete` to allow filtered choices. This can be useful for a large list of choices.
Use `options.caseSensitive` to make autocomplete filters case sensitive. Default `false`
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
Use `options.skip` to skip prompt. It will return the first non-separator choice.
Use `Separator` items in `choices` to visually group options. Separators are not selectable and are skipped during keyboard navigation. When `autocomplete` is active and the user has typed a filter, separators are hidden.
```js
import { select } from "@topcli/prompts";
const framework = await select("Choose a framework", {
choices: [
{ type: "separator", label: "Frontend" },
{ value: "react", label: "React" },
{ value: "vue", label: "Vue" },
{ type: "separator", label: "Backend" },
{ value: "express", label: "Express" },
{ value: "fastify", label: "Fastify" },
]
});
```
Use `choice.disabled` to mark a choice as non-selectable.
```js
const runner = await select("Choose a runner", {
choices: [
{ value: "node", label: "Node.js" },
{ value: "bun", label: "Bun", disabled: "not available" },
{ value: "deno", label: "Deno", disabled: true }
]
});
```
### `multiselect()`
```ts
multiselect(message: string, options: MultiselectOptions): Promise
```
Scrollable multiselect depending `options.maxVisible` (default `8`).
Use `options.preSelectedChoices` to pre-select choices.
Use `options.validators` to handle user input.
Use `options.showHint: false` to disable hint (this option is truthy by default).
Use `options.autocomplete` to allow filtered choices. This can be useful for a large list of choices.
Use `options.caseSensitive` to make autocomplete filters case sensitive. Default `false`.
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
Use `options.skip` to skip prompt. It will return `options.preSelectedChoices` if given, `[]` otherwise.
Use `Separator` items in `choices` to visually group options. Separators are not selectable and are skipped during keyboard navigation. When `autocomplete` is active and the user has typed a filter, separators are hidden.
Use `choice.disabled` to mark a choice as non-selectable.
### `confirm()`
```ts
confirm(message: string, options?: ConfirmOptions): Promise
```
Boolean prompt, default to `options.initial` (`false`).
> [!TIP]
> You can answer pressing Y or N
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
Use `options.skip` to skip prompt. It will return `options.initial` (`false` by default)
### `PromptAgent`
The `PromptAgent` class allows to programmatically set the next answers for any prompt function, this can be useful for testing.
```ts
const agent = PromptAgent.agent();
agent.nextAnswer("John");
const input = await question("What's your name?");
assert.equal(input, "John");
```
> [!WARNING]
> Answers set with `PromptAgent` will **bypass** any logical & validation rules.
> Examples:
> - When using `question()`, `validators` functions will not be executed.
> - When using `select()`, the answer can be different from the available choices.
> - When using `confirm()`, the answer can be any type other than boolean.
> - etc
> **Use with caution**
## Errors
### `AbortError`
```ts
export class AbortError extends Error {
constructor(message: string) {
super(message);
this.name = "AbortError";
}
}
```
## Interfaces
```ts
type Stdin = NodeJS.ReadStream & {
fd: 0;
};
type Stdout = NodeJS.WriteStream & {
fd: 1;
}
export interface AbstractPromptOptions {
stdin?: Stdin;
stdout?: Stdout;
message: string;
skip?: boolean;
signal?: AbortSignal;
}
export interface PromptValidator {
validate: (input: T) => ValidationResponse | Promise;
}
export interface PromptTransformer {
transform: (input: string) => TransformationResponse | Promise>;
}
export type ValidTransformationResponse = {
isValid: true;
transformed: T;
};
export type TransformationResponse = InvalidResponse | ValidTransformationResponse;
export interface QuestionOptions extends AbstractPromptOptions {
defaultValue?: string;
hint?: string;
validators?: PromptValidator[];
transformer?: PromptTransformer;
secure?: boolean | { placeholder: string };
}
export interface Choice {
value: T;
label: string;
description?: string;
disabled?: boolean | string;
}
export interface Separator {
type: "separator";
label?: string;
}
export interface SelectOptions extends AbstractPromptOptions {
choices: (Choice | T | Separator)[];
maxVisible?: number;
ignoreValues?: (T | number | boolean)[];
validators?: PromptValidator[];
autocomplete?: boolean;
caseSensitive?: boolean;
}
export interface MultiselectOptions extends AbstractPromptOptions {
choices: (Choice | T | Separator)[];
maxVisible?: number;
preSelectedChoices?: (Choice | T)[];
validators?: PromptValidator[];
autocomplete?: boolean;
caseSensitive?: boolean;
showHint?: boolean;
}
export interface ConfirmOptions extends AbstractPromptOptions {
initial?: boolean;
}
```
## Contributing
Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
Open an issue if you want to provide feedback such as bug reports or enchancements.
## Contributors
PierreDemailly
💻 ⚠️
Gentilhomme
👀 💻 📖
Tony Gorez
👀
Yefis
💻 📖
Ben
📖 🚧
Takeshi Kondo
🚧
FredGuiou
💻 ⚠️ 📖
Marcus Reinhardt
💻 ⚠️ 📖
Harper Andrews
📖