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: 24 days 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 2 years ago)
- Default Branch: main
- Last Pushed: 2025-09-02T15:58:28.000Z (about 1 month ago)
- Last Synced: 2025-09-03T01:41:44.174Z (about 1 month ago)
- Topics: cli, nodejs, prompt, prompts
- Language: TypeScript
- Homepage:
- Size: 600 KB
- Stars: 33
- Watchers: 3
- Forks: 5
- Open Issues: 3
-
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/) v20 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?: PromptOptions): Promise
```
Simple prompt, similar to `rl.question()` with an improved UI.
Use `options.defaultValue` to set a default value.
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 handle user input.
Use `options.skip` to skip prompt. It will return `options.defaultValue` if given, `""` otherwise.
**Example**
```js
const packageName = await question('Package name', {
validators: [
{
validate: (value) => {
if (fs.existsSync(path.join(process.cwd(), value))) {
return `Folder ${value} already exists`;
}
}
}
]
});
```
**This package provide some validators for common usage**
- required
```js
import { question, required } from "@topcli/prompts";
const name = await question("What's your name ?", {
validators: [required()]
});
```
### `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 choice.
### `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.
### `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) => boolean;
}
export interface QuestionOptions extends SharedOptions {
defaultValue?: string;
validators?: PromptValidator[];
secure?: boolean;
}
export interface Choice {
value: T;
label: string;
description?: string;
}
export interface SelectOptions extends AbstractPromptOptions {
choices: (Choice | T)[];
maxVisible?: number;
ignoreValues?: (T | number | boolean)[];
validators?: PromptValidator[];
autocomplete?: boolean;
caseSensitive?: boolean;
}
export interface MultiselectOptions extends AbstractPromptOptions {
choices: (Choice | T)[];
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
📖