Get started with Enquirer, the most powerful and easy-to-use Node.js library for creating interactive CLI prompts.
Sign in to like and favorite skills
Stylish CLI prompts that are user-friendly, intuitive and easy to create.
>_ Prompts should be more like conversations than inquisitions▌
Created by jonschlinkert and doowb, Enquirer is fast, easy to use, and lightweight enough for small projects, while also being powerful and customizable enough for the most advanced use cases.
Get started with Enquirer, the most powerful and easy-to-use Node.js library for creating interactive CLI prompts.
Install with npm:
$ npm install --save enquirer
(Requires Node.js 8.6 or higher. Please let us know if you need support for an earlier version by creating an issue.)
The easiest way to get started with enquirer is to pass a question object to the
promptconst { prompt } = require('enquirer'); const response = await prompt({ type: 'input', name: 'username', message: 'What is your username?' }); console.log(response); //=> { username: 'jonschlinkert' }
(Examples with
need to be run inside an await
function)async
Pass an array of "question" objects to run a series of prompts.
const response = await prompt([ { type: 'input', name: 'name', message: 'What is your name?' }, { type: 'input', name: 'username', message: 'What is your username?' } ]); console.log(response); //=> { name: 'Edward Chan', username: 'edwardmchan' }
Create an instance of
EnquirerParams
optionsanswersExample
const Enquirer = require('enquirer'); const enquirer = new Enquirer();
Register a custom prompt type.
Params
typefnPromptPromptreturnsExample
const Enquirer = require('enquirer'); const enquirer = new Enquirer(); enquirer.register('customType', require('./custom-prompt'));
Prompt function that takes a "question" object or array of question objects, and returns an object with responses from the user.
Params
questionsreturnsExample
const Enquirer = require('enquirer'); const enquirer = new Enquirer(); const response = await enquirer.prompt({ type: 'input', name: 'username', message: 'What is your username?' }); console.log(response);
Use an enquirer plugin.
Params
pluginreturnsExample
const Enquirer = require('enquirer'); const enquirer = new Enquirer(); const plugin = enquirer => { // do stuff to enquire instance }; enquirer.use(plugin);
Prompt function that takes a "question" object or array of question objects, and returns an object with responses from the user.
Params
questionsreturnsExample
const { prompt } = require('enquirer'); const response = await prompt({ type: 'input', name: 'username', message: 'What is your username?' }); console.log(response);
TextPrompt that auto-completes as the user types, and returns the selected value as a string.
Related prompts
Prompt that returns
truefalse
Related prompts
Prompt that takes user input and returns a string.
Related prompts
Prompt that takes user input, hides it from the terminal, and returns a string.
Related prompts
Prompt that returns a list of values, created by splitting the user input. The default split character is
,
Related prompts
Prompt that allows the user to select multiple items from a list of options.
Related prompts
Prompt that takes a number as input.
Related prompts
Prompt that takes user input and masks it in the terminal. Also see the invisible prompt
Related prompts
Prompt that allows the user to select from a list of options.
Related prompts
Prompt that allows the user to replace placeholders in a snippet of code or text.
Related prompts
Prompt that allows the user to sort items in a list.
Example
In this example, custom styling is applied to the returned values to make it easier to see what's happening.
Related prompts
Prompt that allows the user to provide feedback for a list of questions.
Related prompts
todo
todo
todo
todo
Key combinations that may be used with all prompts.
| command | description |
|---|---|
| ctrl+a | Move the cursor to the first character in user input. |
| ctrl+c | Cancel the prompt. |
| ctrl+g | Reset the prompt to its initial state. |
Key combinations that may be used on prompts that support user input, such as the input prompt, password prompt, and invisible prompt).
| command | description |
|---|---|
| left | Move the cursor forward one character. |
| right | Move the cursor back one character. |
| ctrl+a | Move cursor to the start of the line |
| ctrl+e | Move cursor to the end of the line |
| ctrl+b | Move cursor back one character |
| ctrl+f | Move cursor forward one character |
| ctrl+x | Toggle between first and cursor position |
These key combinations may be used on prompts that support multiple choices, such as the multiselect prompt, or the select prompt when the
multiple| command | description |
|---|---|
| space | Toggle the currently selected choice when |
| number | Move the pointer to the choice at the given index. Also toggles the selected choice when |
| a | Toggle all choices to be enabled or disabled. |
| i | Invert the current selection of choices. |
| g | Toggle the current choice group. |
| command | description |
|---|---|
| fn+up | Decrease the number of visible choices by one. |
| fn+down | Increase the number of visible choices by one. |
| command | description |
|---|---|
| number | Move the pointer to the choice at the given index. Also toggles the selected choice when |
| up | Move the pointer up. |
| down | Move the pointer down. |
| ctrl+a | Move the pointer to the first visible choice. |
| ctrl+e | Move the pointer to the last visible choice. |
| (mac) fn+left / (win) home | Move the pointer to the first choice in the choices array. |
| (mac) fn+right / (win) end | Move the pointer to the last choice in the choices array. |
| shift+up | Scroll up one choice without changing pointer position (locks the pointer while scrolling). |
| shift+down | Scroll down one choice without changing pointer position (locks the pointer while scrolling). |
Each prompt takes an options object (aka "question" object), that implements the following interface:
{ type: string | function, name: string | function, message: string | function | async function, initial: string | function | async function format: function | async function, result: function | async function, validate: function | async function }
| Property | Type | Description |
|---|---|---|
| | Enquirer uses this value to determine the type of prompt to run, but it's optional when prompts are run directly. |
| | Used as the key for the answer on the returned values (answers) object. |
| | The message to display when the prompt is rendered in the terminal. |
| | The default value to return if the user does not supply a value. |
| | Function to format user input in the terminal. |
| | Function to format the final submitted value before it's returned. |
| | Function to validate the submitted value before it's returned. This function may return a boolean or a string. If a string is returned it will be used as the validation error message. |
(
, type
and name
are required).message
Example
const question = { type: 'select', name: 'color', message: 'Favorite color?', initial: 1, choices: [ { name: 'red', message: 'Red', value: '#ff0000' }, { name: 'green', message: 'Green', value: '#00ff00' }, { name: 'blue', message: 'Blue', value: '#0000ff' } ] };
Choice { name: string; message: string | undefined; value: string | undefined; hint: string | undefined; disabled: boolean | string | undefined; }
| Property | Type | Description |
|---|---|---|
| | The unique key to identify a choice |
| | The message to display in the terminal |
| | An optional value to associate with the choice. This is useful for creating key-value pairs from user choices. |
| | Value to display to provide user help next to a choice. |
| | Disable a choice so that it cannot be selected. This value may either be |
Please see CHANGELOG.md.
MacBook Pro, Intel Core i7, 2.5 GHz, 16 GB.
Time it takes for the module to load the first time (average of 3 runs):
enquirer: 4.013ms inquirer: 286.717ms prompts: 17.010ms
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm test
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
$ npm install -g verbose/verb#dev verb-generate-readme && verb
| Commits | Contributor |
|---|---|
| 72 | jonschlinkert |
| 12 | doowb |
| 1 | mischah |
| 1 | skellock |
Jon Schlinkert
Thanks to derhuerst, creator of prompt libraries such as prompt-skeleton, which influenced some of the concepts we used in our prompts.
Copyright © 2018, Jon Schlinkert. Released under the MIT License.