Enquirer

Stylish, intuitive and user-friendly prompts, for Node.js. Used by eslint, ...

CLI
enquirer/enquirerenquirer

README

Enquirer

version travis downloads


Stylish CLI prompts that are user-friendly, intuitive and easy to create.
>_ Prompts should be more like conversations than inquisitions▌

(Example shows Enquirer's Survey Prompt) Enquirer Survey Prompt
The terminal in all examples is Hyper, theme is hyper-monokai-extended.

See more prompt examples



Created by [jonschlinkert][jon] and [doowb][brian], 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.

- Fast - Loads in ~4ms (that's about _3-4 times faster than a single frame of a HD movie at 60fps_)
- Lightweight - Only one dependency, the excellent ansi-colors by Brian Woodward.
- Easy to implement - Uses promises and async/await and sensible defaults to make prompts easy to create and implement.
- Easy to use - Thrill your users with a better experience! Navigating around input and choices is a breeze. You can even create quizzes, or record and playback key bindings to aid with tutorials and videos.
- Intuitive - Keypress combos are available to simplify usage.
- Flexible - All prompts can be used standalone or chained together.
- Stylish - Easily override semantic styles and symbols for any part of the prompt.
- Extensible - Easily create and use custom prompts by extending Enquirer's built-in prompts.
- Pluggable - Add advanced features to Enquirer using plugins.
- Validation - Optionally validate user input with any prompt.
- Well tested - All prompts are well-tested, and tests are easy to create without having to use brittle, hacky solutions to spy on prompts or "inject" values.
- Examples - There are numerous examples available to help you get started.

If you like Enquirer, please consider starring or tweeting about this project to show your support. Thanks!

[issue]: https://github.com/enquirer/enquirer/issues/new
[pulls]: https://github.com/enquirer/enquirer/pulls
[jon]: https://github.com/jonschlinkert
[brian]: https://github.com/doowb

>_ Ready to start making prompts your users will love? ▌
Enquirer Select Prompt with heartbeat example



❯ Getting started


Get started with Enquirer, the most powerful and easy-to-use Node.js library for creating interactive CLI prompts.

- Install
- Usage
- Enquirer
- Prompts
  Built-in Prompts
  Custom Prompts
- Key Bindings
- Options
- Release History
- Performance
- About

❯ Install

Install with npm:

  1. ```sh
  2. $ npm install enquirer --save
  3. ```
Install with yarn:

  1. ```sh
  2. $ yarn add enquirer
  3. ```

Install Enquirer with NPM


_(Requires Node.js 8.6 or higher. Please let us know if you need support for an earlier version by creating an issue.)_

❯ Usage

Single prompt


The easiest way to get started with enquirer is to pass a question object to theprompt method.

  1. ``` js
  2. const { prompt } = require('enquirer');

  4. const response = await prompt({
  5.   type: 'input',
  6.   name: 'username',
  7.   message: 'What is your username?'
  8. });

  10. console.log(response); // { username: 'jonschlinkert' }
  11. ```

_(Examples with await need to be run inside an async function)_

Multiple prompts


Pass an array of "question" objects to run a series of prompts.

  1. ``` js
  2. const response = await prompt([
  3.   {
  4.     type: 'input',
  5.     name: 'name',
  6.     message: 'What is your name?'
  7.   },
  8.   {
  9.     type: 'input',
  10.     name: 'username',
  11.     message: 'What is your username?'
  12.   }
  13. ]);

  15. console.log(response); // { name: 'Edward Chan', username: 'edwardmchan' }
  16. ```

Different ways to run enquirer


1. By importing the specific built-in prompt


  1. ``` js
  2. const { Confirm } = require('enquirer');

  4. const prompt = new Confirm({
  5.   name: 'question',
  6.   message: 'Did you like enquirer?'
  7. });

  9. prompt.run()
  10.   .then(answer => console.log('Answer:', answer));
  11. ```

2. By passing the options to prompt


  1. ``` js
  2. const { prompt } = require('enquirer');

  4. prompt({
  5.   type: 'confirm',
  6.   name: 'question',
  7.   message: 'Did you like enquirer?'
  8. })
  9.   .then(answer => console.log('Answer:', answer));
  10. ```

Jump to: Getting Started · Prompts · Options · Key Bindings

❯ Enquirer

Enquirer is a prompt runner

Add Enquirer to your JavaScript project with following line of code.

  1. ``` js
  2. const Enquirer = require('enquirer');
  3. ```

The main export of this library is the Enquirer class, which has methods and features designed to simplify running prompts.

  1. ``` js
  2. const { prompt } = require('enquirer');
  3. const question = [
  4.   {
  5.     type: 'input',
  6.     name: 'username',
  7.     message: 'What is your username?'
  8.   },
  9.   {
  10.     type: 'password',
  11.     name: 'password',
  12.     message: 'What is your password?'
  13.   }
  14. ];

  16. let answers = await prompt(question);
  17. console.log(answers);
  18. ```

Prompts control how values are rendered and returned

Each individual prompt is a class with special features and functionality for rendering the types of values you want to show users in the terminal, and subsequently returning the types of values you need to use in your application.

How can I customize prompts?

Below in this guide you will find information about creating custom prompts. For now, we'll focus on how to customize an existing prompt.

All of the individual prompt classes in this library are exposed as static properties on Enquirer. This allows them to be used directly without usingenquirer.prompt().

Use this approach if you need to modify a prompt instance, or listen for events on the prompt.

Example

  1. ``` js
  2. const { Input } = require('enquirer');
  3. const prompt = new Input({
  4.   name: 'username',
  5.   message: 'What is your username?'
  6. });

  8. prompt.run()
  9.   .then(answer => console.log('Username:', answer))
  10.   .catch(console.error);
  11. ```

Enquirer API


Enquirer

Create an instance of Enquirer.

Params

options {Object}: (optional) Options to use with all prompts.    
answers {Object}: (optional) Answers object to initialize with.    

Example

  1. ``` js
  2. const Enquirer = require('enquirer');
  3. const enquirer = new Enquirer();
  4. ```

register()

Register a custom prompt type.

Params

type {String}    
fn {Function|Prompt}: Prompt class, or a function that returns a Prompt class.    
returns {Object}: Returns the Enquirer instance  

Example

  1. ``` js
  2. const Enquirer = require('enquirer');
  3. const enquirer = new Enquirer();
  4. enquirer.register('customType', require('./custom-prompt'));
  5. ```

prompt()

Prompt function that takes a "question" object or array of question objects, and returns an object with responses from the user.

Params

questions {Array|Object}: Options objects for one or more prompts to run.    
returns {Promise}: Promise that returns an "answers" object with the user's responses.  

Example

  1. ``` js
  2. const Enquirer = require('enquirer');
  3. const enquirer = new Enquirer();

  5. const response = await enquirer.prompt({
  6.   type: 'input',
  7.   name: 'username',
  8.   message: 'What is your username?'
  9. });
  10. console.log(response);
  11. ```

use()

Use an enquirer plugin.

Params

plugin {Function}: Plugin function that takes an instance of Enquirer.    
returns {Object}: Returns the Enquirer instance.  

Example

  1. ``` js
  2. const Enquirer = require('enquirer');
  3. const enquirer = new Enquirer();
  4. const plugin = enquirer => {
  5.   // do stuff to enquire instance
  6. };
  7. enquirer.use(plugin);
  8. ```

Enquirer#prompt

Prompt function that takes a "question" object or array of question objects, and returns an object with responses from the user.

Params

questions {Array|Object}: Options objects for one or more prompts to run.    
returns {Promise}: Promise that returns an "answers" object with the user's responses.  

Example

  1. ``` js
  2. const { prompt } = require('enquirer');
  3. const response = await prompt({
  4.   type: 'input',
  5.   name: 'username',
  6.   message: 'What is your username?'
  7. });
  8. console.log(response);
  9. ```

❯ Prompts

This section is about Enquirer's prompts: what they look like, how they work, how to run them, available options, and how to customize the prompts or create your own prompt concept.

Getting started with Enquirer's prompts

- Prompt - The basePrompt class used by other prompts
  - Prompt Options
- Built-in prompts
- Prompt Types - The basePrompt class used by other prompts
- Custom Prompts - Enquirer 2.0 introduced the concept of prompt "types", with the goal of making custom prompts easier than ever to create and use.

Prompt


The base Prompt class is used to create all other prompts.

  1. ``` js
  2. const { Prompt } = require('enquirer');
  3. class MyCustomPrompt extends Prompt {}
  4. ```

See the documentation for creating custom prompts to learn more about how this works.

Prompt Options


Each prompt takes an options object (aka "question" object), that implements the following interface:

  1. ``` js
  2. {
  3.   // required
  4.   type: string | function,
  5.   name: string | function,
  6.   message: string | function | async function,

  8.   // optional
  9.   skip: boolean | function | async function,
  10.   initial: string | function | async function,
  11.   format: function | async function,
  12.   result: function | async function,
  13.   validate: function | async function,
  14. }
  15. ```
Each property of the options object is described below:

**Property****Required?****Type****Description**
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`type`yes`string\|function`Enquirer
`name`yes`string\|function`Used
`message`yes`string\|function`The
`skip`no`boolean\|function`If
`initial`no`string\|function`The
`format`no`function`Function
`result`no`function`Function
`validate`no`function`Function

Example usage

  1. ``` js
  2. const { prompt } = require('enquirer');

  4. const question = {
  5.   type: 'input',
  6.   name: 'username',
  7.   message: 'What is your username?'
  8. };

  10. prompt(question)
  11.   .then(answer => console.log('Answer:', answer))
  12.   .catch(console.error);
  13. ```

❯ Built-in prompts


- AutoComplete Prompt
- BasicAuth Prompt
- Confirm Prompt
- Form Prompt
- Input Prompt
- Invisible Prompt
- List Prompt
- MultiSelect Prompt
- Numeral Prompt
- Password Prompt
- Quiz Prompt
- Survey Prompt
- Scale Prompt
- Select Prompt
- Sort Prompt
- Snippet Prompt
- Toggle Prompt

AutoComplete Prompt


Prompt that auto-completes as the user types, and returns the selected value as a string.

Enquirer AutoComplete Prompt


Example Usage

  1. ``` js
  2. const { AutoComplete } = require('enquirer');

  4. const prompt = new AutoComplete({
  5.   name: 'flavor',
  6.   message: 'Pick your favorite flavor',
  7.   limit: 10,
  8.   initial: 2,
  9.   choices: [
  10.     'Almond',
  11.     'Apple',
  12.     'Banana',
  13.     'Blackberry',
  14.     'Blueberry',
  15.     'Cherry',
  16.     'Chocolate',
  17.     'Cinnamon',
  18.     'Coconut',
  19.     'Cranberry',
  20.     'Grape',
  21.     'Nougat',
  22.     'Orange',
  23.     'Pear',
  24.     'Pineapple',
  25.     'Raspberry',
  26.     'Strawberry',
  27.     'Vanilla',
  28.     'Watermelon',
  29.     'Wintergreen'
  30.   ]
  31. });

  33. prompt.run()
  34.   .then(answer => console.log('Answer:', answer))
  35.   .catch(console.error);
  36. ```

AutoComplete Options

OptionTypeDefaultDescription
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`highlight``function``dim`The
`multiple``boolean``false`Allow
`suggest``function`GreedyFunction
`initial``number`0Preselected
`footer``function`NoneFunction

Related prompts

- Select
- MultiSelect
- Survey

↑ back to: Getting Started · Prompts


BasicAuth Prompt


Prompt that asks for username and password to authenticate the user. The default implementation of authenticate function in BasicAuth prompt is to compare the username and password with the values supplied while running the prompt. The implementer is expected to override the authenticate function with a custom logic such as making an API request to a server to authenticate the username and password entered and expect a token back.

Enquirer BasicAuth Prompt


Example Usage

  1. ``` js
  2. const { BasicAuth } = require('enquirer');

  4. const prompt = new BasicAuth({
  5.   name: 'password',
  6.   message: 'Please enter your password',
  7.   username: 'rajat-sr',
  8.   password: '123',
  9.   showPassword: true
  10. });

  12. prompt
  13.   .run()
  14.   .then(answer => console.log('Answer:', answer))
  15.   .catch(console.error);
  16. ```

↑ back to: Getting Started · Prompts


Confirm Prompt


Prompt that returns true or false.

Enquirer Confirm Prompt


Example Usage

  1. ``` js
  2. const { Confirm } = require('enquirer');

  4. const prompt = new Confirm({
  5.   name: 'question',
  6.   message: 'Want to answer?'
  7. });

  9. prompt.run()
  10.   .then(answer => console.log('Answer:', answer))
  11.   .catch(console.error);
  12. ```

Related prompts

- Input
- Numeral
- Password

↑ back to: Getting Started · Prompts


Form Prompt


Prompt that allows the user to enter and submit multiple values on a single terminal screen.

Enquirer Form Prompt


Example Usage

  1. ``` js
  2. const { Form } = require('enquirer');

  4. const prompt = new Form({
  5.   name: 'user',
  6.   message: 'Please provide the following information:',
  7.   choices: [
  8.     { name: 'firstname', message: 'First Name', initial: 'Jon' },
  9.     { name: 'lastname', message: 'Last Name', initial: 'Schlinkert' },
  10.     { name: 'username', message: 'GitHub username', initial: 'jonschlinkert' }
  11.   ]
  12. });

  14. prompt.run()
  15.   .then(value => console.log('Answer:', value))
  16.   .catch(console.error);
  17. ```

Related prompts

- Input
- Survey

↑ back to: Getting Started · Prompts


Input Prompt


Prompt that takes user input and returns a string.

Enquirer Input Prompt


Example Usage

  1. ``` js
  2. const { Input } = require('enquirer');
  3. const prompt = new Input({
  4.   message: 'What is your username?',
  5.   initial: 'jonschlinkert'
  6. });

  8. prompt.run()
  9.   .then(answer => console.log('Answer:', answer))
  10.   .catch(console.log);
  11. ```

You can use data-store to store input history that the user can cycle through (see source).

Related prompts

- Confirm
- Numeral
- Password

↑ back to: Getting Started · Prompts


Invisible Prompt


Prompt that takes user input, hides it from the terminal, and returns a string.

Enquirer Invisible Prompt


Example Usage

  1. ``` js
  2. const { Invisible } = require('enquirer');
  3. const prompt = new Invisible({
  4.   name: 'secret',
  5.   message: 'What is your secret?'
  6. });

  8. prompt.run()
  9.   .then(answer => console.log('Answer:', { secret: answer }))
  10.   .catch(console.error);
  11. ```

Related prompts

- Password
- Input

↑ back to: Getting Started · Prompts


List Prompt


Prompt that returns a list of values, created by splitting the user input. The default split character is , with optional trailing whitespace.

Enquirer List Prompt


Example Usage

  1. ``` js
  2. const { List } = require('enquirer');
  3. const prompt = new List({
  4.   name: 'keywords',
  5.   message: 'Type comma-separated keywords'
  6. });

  8. prompt.run()
  9.   .then(answer => console.log('Answer:', answer))
  10.   .catch(console.error);
  11. ```

Related prompts

- Sort
- Select

↑ back to: Getting Started · Prompts


MultiSelect Prompt


Prompt that allows the user to select multiple items from a list of options.

Enquirer MultiSelect Prompt


Example Usage

  1. ``` js
  2. const { MultiSelect } = require('enquirer');

  4. const prompt = new MultiSelect({
  5.   name: 'value',
  6.   message: 'Pick your favorite colors',
  7.   limit: 7,
  8.   choices: [
  9.     { name: 'aqua', value: '#00ffff' },
  10.     { name: 'black', value: '#000000' },
  11.     { name: 'blue', value: '#0000ff' },
  12.     { name: 'fuchsia', value: '#ff00ff' },
  13.     { name: 'gray', value: '#808080' },
  14.     { name: 'green', value: '#008000' },
  15.     { name: 'lime', value: '#00ff00' },
  16.     { name: 'maroon', value: '#800000' },
  17.     { name: 'navy', value: '#000080' },
  18.     { name: 'olive', value: '#808000' },
  19.     { name: 'purple', value: '#800080' },
  20.     { name: 'red', value: '#ff0000' },
  21.     { name: 'silver', value: '#c0c0c0' },
  22.     { name: 'teal', value: '#008080' },
  23.     { name: 'white', value: '#ffffff' },
  24.     { name: 'yellow', value: '#ffff00' }
  25.   ]
  26. });

  28. prompt.run()
  29.   .then(answer => console.log('Answer:', answer))
  30.   .catch(console.error);

  32. // Answer: ['aqua', 'blue', 'fuchsia']
  33. ```

Example key-value pairs

Optionally, pass a result function and use the .map method to return an object of key-value pairs of the selected names and values: example

  1. ``` js
  2. const { MultiSelect } = require('enquirer');

  4. const prompt = new MultiSelect({
  5.   name: 'value',
  6.   message: 'Pick your favorite colors',
  7.   limit: 7,
  8.   choices: [
  9.     { name: 'aqua', value: '#00ffff' },
  10.     { name: 'black', value: '#000000' },
  11.     { name: 'blue', value: '#0000ff' },
  12.     { name: 'fuchsia', value: '#ff00ff' },
  13.     { name: 'gray', value: '#808080' },
  14.     { name: 'green', value: '#008000' },
  15.     { name: 'lime', value: '#00ff00' },
  16.     { name: 'maroon', value: '#800000' },
  17.     { name: 'navy', value: '#000080' },
  18.     { name: 'olive', value: '#808000' },
  19.     { name: 'purple', value: '#800080' },
  20.     { name: 'red', value: '#ff0000' },
  21.     { name: 'silver', value: '#c0c0c0' },
  22.     { name: 'teal', value: '#008080' },
  23.     { name: 'white', value: '#ffffff' },
  24.     { name: 'yellow', value: '#ffff00' }
  25.   ],
  26.   result(names) {
  27.    return this.map(names);
  28.   }
  29. });

  31. prompt.run()
  32.   .then(answer => console.log('Answer:', answer))
  33.   .catch(console.error);

  35. // Answer: { aqua: '#00ffff', blue: '#0000ff', fuchsia: '#ff00ff' }
  36. ```

Related prompts

- AutoComplete
- Select
- Survey

↑ back to: Getting Started · Prompts


Numeral Prompt


Prompt that takes a number as input.

Enquirer Numeral Prompt


Example Usage

  1. ``` js
  2. const { NumberPrompt } = require('enquirer');

  4. const prompt = new NumberPrompt({
  5.   name: 'number',
  6.   message: 'Please enter a number'
  7. });

  9. prompt.run()
  10.   .then(answer => console.log('Answer:', answer))
  11.   .catch(console.error);
  12. ```

Related prompts

- Input
- Confirm

↑ back to: Getting Started · Prompts


Password Prompt


Prompt that takes user input and masks it in the terminal. Also see the invisible prompt

Enquirer Password Prompt


Example Usage

  1. ``` js
  2. const { Password } = require('enquirer');

  4. const prompt = new Password({
  5.   name: 'password',
  6.   message: 'What is your password?'
  7. });

  9. prompt.run()
  10.   .then(answer => console.log('Answer:', answer))
  11.   .catch(console.error);
  12. ```

Related prompts

- Input
- Invisible

↑ back to: Getting Started · Prompts


Quiz Prompt


Prompt that allows the user to play multiple-choice quiz questions.

Enquirer Quiz Prompt


Example Usage

  1. ``` js
  2. const { Quiz } = require('enquirer');

  4. const prompt = new Quiz({
  5.   name: 'countries',
  6.   message: 'How many countries are there in the world?',
  7.   choices: ['165', '175', '185', '195', '205'],
  8.   correctChoice: 3
  9. });

  11. prompt
  12.   .run()
  13.   .then(answer => {
  14.     if (answer.correct) {
  15.       console.log('Correct!');
  16.     } else {
  17.       console.log(`Wrong! Correct answer is ${answer.correctAnswer}`);
  18.     }
  19.   })
  20.   .catch(console.error);
  21. ```

Quiz Options

OptionTypeRequiredDescription
-------------------------------------------------------------------------------------------------------------------------------------------
`choices``array`YesThe
`correctChoice`|YesIndex

↑ back to: Getting Started · Prompts


Survey Prompt


Prompt that allows the user to provide feedback for a list of questions.

Enquirer Survey Prompt


Example Usage

  1. ``` js
  2. const { Survey } = require('enquirer');

  4. const prompt = new Survey({
  5.   name: 'experience',
  6.   message: 'Please rate your experience',
  7.    scale: [
  8.     { name: '1', message: 'Strongly Disagree' },
  9.     { name: '2', message: 'Disagree' },
  10.     { name: '3', message: 'Neutral' },
  11.     { name: '4', message: 'Agree' },
  12.     { name: '5', message: 'Strongly Agree' }
  13.   ],
  14.   margin: [0, 0, 2, 1],
  15.   choices: [
  16.     {
  17.       name: 'interface',
  18.       message: 'The website has a friendly interface.'
  19.     },
  20.     {
  21.       name: 'navigation',
  22.       message: 'The website is easy to navigate.'
  23.     },
  24.     {
  25.       name: 'images',
  26.       message: 'The website usually has good images.'
  27.     },
  28.     {
  29.       name: 'upload',
  30.       message: 'The website makes it easy to upload images.'
  31.     },
  32.     {
  33.       name: 'colors',
  34.       message: 'The website has a pleasing color palette.'
  35.     }
  36.   ]
  37. });

  39. prompt.run()
  40.   .then(value => console.log('ANSWERS:', value))
  41.   .catch(console.error);
  42. ```

Related prompts

- Scale
- Snippet
- Select


Scale Prompt


A more compact version of the Survey prompt, the Scale prompt allows the user to quickly provide feedback using a Likert Scale.

Enquirer Scale Prompt


Example Usage

  1. ``` js
  2. const { Scale } = require('enquirer');
  3. const prompt = new Scale({
  4.   name: 'experience',
  5.   message: 'Please rate your experience',
  6.   scale: [
  7.     { name: '1', message: 'Strongly Disagree' },
  8.     { name: '2', message: 'Disagree' },
  9.     { name: '3', message: 'Neutral' },
  10.     { name: '4', message: 'Agree' },
  11.     { name: '5', message: 'Strongly Agree' }
  12.   ],
  13.   margin: [0, 0, 2, 1],
  14.   choices: [
  15.     {
  16.       name: 'interface',
  17.       message: 'The website has a friendly interface.',
  18.       initial: 2
  19.     },
  20.     {
  21.       name: 'navigation',
  22.       message: 'The website is easy to navigate.',
  23.       initial: 2
  24.     },
  25.     {
  26.       name: 'images',
  27.       message: 'The website usually has good images.',
  28.       initial: 2
  29.     },
  30.     {
  31.       name: 'upload',
  32.       message: 'The website makes it easy to upload images.',
  33.       initial: 2
  34.     },
  35.     {
  36.       name: 'colors',
  37.       message: 'The website has a pleasing color palette.',
  38.       initial: 2
  39.     }
  40.   ]
  41. });

  43. prompt.run()
  44.   .then(value => console.log('ANSWERS:', value))
  45.   .catch(console.error);
  46. ```

Related prompts

- AutoComplete
- Select
- Survey

↑ back to: Getting Started · Prompts


Select Prompt


Prompt that allows the user to select from a list of options.

Enquirer Select Prompt


Example Usage

  1. ``` js
  2. const { Select } = require('enquirer');

  4. const prompt = new Select({
  5.   name: 'color',
  6.   message: 'Pick a flavor',
  7.   choices: ['apple', 'grape', 'watermelon', 'cherry', 'orange']
  8. });

  10. prompt.run()
  11.   .then(answer => console.log('Answer:', answer))
  12.   .catch(console.error);
  13. ```

Related prompts

- AutoComplete
- MultiSelect

↑ back to: Getting Started · Prompts


Sort Prompt


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.

Enquirer Sort Prompt


Example Usage

  1. ``` js
  2. const colors = require('ansi-colors');
  3. const { Sort } = require('enquirer');
  4. const prompt = new Sort({
  5.   name: 'colors',
  6.   message: 'Sort the colors in order of preference',
  7.   hint: 'Top is best, bottom is worst',
  8.   numbered: true,
  9.   choices: ['red', 'white', 'green', 'cyan', 'yellow'].map(n => ({
  10.     name: n,
  11.     message: colors[n](n)
  12.   }))
  13. });

  15. prompt.run()
  16.   .then(function(answer = []) {
  17.     console.log(answer);
  18.     console.log('Your preferred order of colors is:');
  19.     console.log(answer.map(key => colors[key](key)).join('\n'));
  20.   })
  21.   .catch(console.error);
  22. ```

Related prompts

- List
- Select

↑ back to: Getting Started · Prompts


Snippet Prompt


Prompt that allows the user to replace placeholders in a snippet of code or text.

Prompts


Example Usage

  1. ``` js
  2. const semver = require('semver');
  3. const { Snippet } = require('enquirer');
  4. const prompt = new Snippet({
  5.   name: 'username',
  6.   message: 'Fill out the fields in package.json',
  7.   required: true,
  8.   fields: [
  9.     {
  10.       name: 'author_name',
  11.       message: 'Author Name'
  12.     },
  13.     {
  14.       name: 'version',
  15.       validate(value, state, item, index) {
  16.         if (item && item.name === 'version' && !semver.valid(value)) {
  17.           return prompt.styles.danger('version should be a valid semver value');
  18.         }
  19.         return true;
  20.       }
  21.     }
  22.   ],
  23.   template: `{
  24.   "name": "\${name}",
  25.   "description": "\${description}",
  26.   "version": "\${version}",
  27.   "homepage": "https://github.com/\${username}/\${name}",
  28.   "author": "\${author_name} (https://github.com/\${username})",
  29.   "repository": "\${username}/\${name}",
  30.   "license": "\${license:ISC}"
  31. }
  32. `
  33. });

  35. prompt.run()
  36.   .then(answer => console.log('Answer:', answer.result))
  37.   .catch(console.error);
  38. ```

Related prompts

- Survey
- AutoComplete

↑ back to: Getting Started · Prompts


Toggle Prompt


Prompt that allows the user to toggle between two values then returns true or false.

Enquirer Toggle Prompt


Example Usage

  1. ``` js
  2. const { Toggle } = require('enquirer');

  4. const prompt = new Toggle({
  5.   message: 'Want to answer?',
  6.   enabled: 'Yep',
  7.   disabled: 'Nope'
  8. });

  10. prompt.run()
  11.   .then(answer => console.log('Answer:', answer))
  12.   .catch(console.error);
  13. ```

Related prompts

- Confirm
- Input
- Sort

↑ back to: Getting Started · Prompts


Prompt Types

There are 5 (soon to be 6!) type classes:
ArrayPrompt
    - Options
    - Properties
    - Methods
    - Choices
    - Defining choices
    - Choice properties
    - Related prompts
AuthPrompt
BooleanPrompt
DatePrompt (Coming Soon!)
NumberPrompt
StringPrompt

Each type is a low-level class that may be used as a starting point for creating higher level prompts. Continue reading to learn how.

ArrayPrompt


The ArrayPrompt class is used for creating prompts that display a list of choices in the terminal. For example, Enquirer uses this class as the basis for the Select and Survey prompts.

Options


In addition to the options available to all prompts, Array prompts also support the following options.

**Option****Required?****Type****Description**
--------------------------------------------------------------------------------------------------------------------------------------------------------------
`autofocus``no``string\|number`The
`stdin``no``stream`The
`stdout``no``stream`The
|

Properties


Array prompts have the following instance properties and getters.

**Property**Type****Description**
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`choices``array`Array
`cursor``number`Position
`enabled``array`Returns
`focused``array`Returns
`focused`Gets
`index``number`Position
`limit``number`The
`selected``array`Either
`visible``string`|

Methods


**Method****Description**
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`pointer()`Returns
`indicator()`Returns
`focus()`Sets

Choices


Array prompts support the choices option, which is the array of choices users will be able to select from when rendered in the terminal.

Type: string|object

Example

  1. ``` js
  2. const { prompt } = require('enquirer');

  4. const questions = [{
  5.   type: 'select',
  6.   name: 'color',
  7.   message: 'Favorite color?',
  8.   initial: 1,
  9.   choices: [
  10.     { name: 'red',   message: 'Red',   value: '#ff0000' }, //<= choice object
  11.     { name: 'green', message: 'Green', value: '#00ff00' }, //<= choice object
  12.     { name: 'blue',  message: 'Blue',  value: '#0000ff' }  //<= choice object
  13.   ]
  14. }];

  16. let answers = await prompt(questions);
  17. console.log('Answer:', answers.color);
  18. ```

Defining choices


Whether defined as a string or object, choices are normalized to the following interface:

  1. ``` js
  2. {
  3.   name: string;
  4.   message: string | undefined;
  5.   value: string | undefined;
  6.   hint: string | undefined;
  7.   disabled: boolean | string | undefined;
  8. }
  9. ```

Example

  1. ``` js
  2. const question = {
  3.   name: 'fruit',
  4.   message: 'Favorite fruit?',
  5.   choices: ['Apple', 'Orange', 'Raspberry']
  6. };
  7. ```

Normalizes to the following when the prompt is run:

  1. ``` js
  2. const question = {
  3.   name: 'fruit',
  4.   message: 'Favorite fruit?',
  5.   choices: [
  6.     { name: 'Apple', message: 'Apple', value: 'Apple' },
  7.     { name: 'Orange', message: 'Orange', value: 'Orange' },
  8.     { name: 'Raspberry', message: 'Raspberry', value: 'Raspberry' }
  9.   ]
  10. };
  11. ```

Choice properties


The following properties are supported on choice objects.

**Option****Type****Description**
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`name``string`The
`message``string`The
`value``string`Value
`choices``array`Array
`hint``string`Help
`role``string`Determines
`enabled``boolean`Enabled
`disabled``boolean\|string`Disable
`indicator``string\|function`Custom

Related prompts


- AutoComplete
- Form
- MultiSelect
- Select
- Survey


AuthPrompt


The AuthPrompt is used to create prompts to log in user using any authentication method. For example, Enquirer uses this class as the basis for the BasicAuth Prompt. You can also find prompt examples inexamples/auth/ folder that utilizes AuthPrompt to create OAuth based authentication prompt or a prompt that authenticates using time-based OTP, among others.

AuthPrompt has a factory function that creates an instance of AuthPrompt class and it expects an authenticate function, as an argument, which overrides the authenticate function of the AuthPrompt class.

Methods


**Method****Description**
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`authenticate()`Contain

Choices


Auth prompt supports the choices option, which is the similar to the choices used in Form Prompt.

Example

  1. ``` js
  2. const { AuthPrompt } = require('enquirer');

  4. function authenticate(value, state) {
  5.   if (value.username === this.options.username && value.password === this.options.password) {
  6.     return true;
  7.   }
  8.   return false;
  9. }

  11. const CustomAuthPrompt = AuthPrompt.create(authenticate);

  13. const prompt = new CustomAuthPrompt({
  14.   name: 'password',
  15.   message: 'Please enter your password',
  16.   username: 'rajat-sr',
  17.   password: '1234567',
  18.   choices: [
  19.     { name: 'username', message: 'username' },
  20.     { name: 'password', message: 'password' }
  21.   ]
  22. });

  24. prompt
  25.   .run()
  26.   .then(answer => console.log('Authenticated?', answer))
  27.   .catch(console.error);
  28. ```

Related prompts


- BasicAuth Prompt


BooleanPrompt


The BooleanPrompt class is used for creating prompts that display and return a boolean value.

  1. ``` js
  2. const { BooleanPrompt } = require('enquirer');

  4. const  prompt = new  BooleanPrompt({
  5.   header:  '========================',
  6.   message:  'Do you love enquirer?',
  7.   footer:  '========================',
  8. });

  10. prompt.run()
  11.   .then(answer  =>  console.log('Selected:', answer))
  12.   .catch(console.error);
  13. ```

Returns: boolean


NumberPrompt


The NumberPrompt class is used for creating prompts that display and return a numerical value.

  1. ``` js
  2. const { NumberPrompt } = require('enquirer');

  4. const  prompt = new  NumberPrompt({
  5.   header:  '************************',
  6.   message:  'Input the Numbers:',
  7.   footer:  '************************',
  8. });

  10. prompt.run()
  11.   .then(answer  =>  console.log('Numbers are:', answer))
  12.   .catch(console.error);
  13. ```

Returns: string|number (number, or number formatted as a string)


StringPrompt


The StringPrompt class is used for creating prompts that display and return a string value.

  1. ``` js
  2. const { StringPrompt } = require('enquirer');

  4. const prompt = new StringPrompt({
  5.   header: '************************',
  6.   message: 'Input the String:',
  7.   footer: '************************'
  8. });

  10. prompt.run()
  11.   .then(answer => console.log('String is:', answer))
  12.   .catch(console.error);
  13. ```

Returns: string

❯ Custom prompts

With Enquirer 2.0, custom prompts are easier than ever to create and use.

How do I create a custom prompt?

Custom prompts are created by extending either:
- Enquirer's Prompt class
- one of the built-in prompts, or
- low-level types.



  1. ``` js
  2. const { Prompt } = require('enquirer');

  4. class HaiKarate extends Prompt {
  5.   constructor(options = {}) {
  6.     super(options);
  7.     this.value = options.initial || 0;
  8.     this.cursorHide();
  9.   }
  10.   up() {
  11.     this.value++;
  12.     this.render();
  13.   }
  14.   down() {
  15.     this.value--;
  16.     this.render();
  17.   }
  18.   render() {
  19.     this.clear(); // clear previously rendered prompt from the terminal
  20.     this.write(`${this.state.message}: ${this.value}`);
  21.   }
  22. }

  24. // Use the prompt by creating an instance of your custom prompt class.
  25. const prompt = new HaiKarate({
  26.   message: 'How many sprays do you want?',
  27.   initial: 10
  28. });

  30. prompt.run()
  31.   .then(answer => console.log('Sprays:', answer))
  32.   .catch(console.error);
  33. ```

If you want to be able to specify your prompt by type so that it may be used alongside other prompts, you will need to first create an instance of Enquirer.

  1. ``` js
  2. const Enquirer = require('enquirer');
  3. const enquirer = new Enquirer();
  4. ```

Then use the .register() method to add your custom prompt.

  1. ``` js
  2. enquirer.register('haikarate', HaiKarate);
  3. ```

Now you can do the following when defining "questions".

  1. ``` js
  2. let spritzer = require('cologne-drone');
  3. let answers = await enquirer.prompt([
  4.   {
  5.     type: 'haikarate',
  6.     name: 'cologne',
  7.     message: 'How many sprays do you need?',
  8.     initial: 10,
  9.     async onSubmit(name, value) {
  10.       await spritzer.activate(value); //<= activate drone
  11.       return value;
  12.     }
  13.   }
  14. ]);
  15. ```

❯ Key Bindings

All prompts


These key combinations may be used with all prompts.

**command****description**
----------------------------------------------------------------------
ctrlCancel
ctrlReset

Move cursor


These combinations may be used on prompts that support user input (eg. input prompt, password prompt, and invisible prompt).

**command****description**
----------------------------------------------------------------------
leftMove
rightMove
ctrlMove
ctrlMove
ctrlMove
ctrlMove
ctrlToggle

Edit Input


These key combinations may be used on prompts that support user input (eg. input prompt, password prompt, and invisible prompt).

**command****description**
----------------------------------------------------------------------
ctrlMove
ctrlMove
ctrlMove
ctrlMove
ctrlToggle

**command**command**description**
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
deletebackspaceDelete
fndeleteDelete
optionaltScroll
optionaltScroll

Select choices


These key combinations may be used on prompts that support _multiple_ choices, such as the multiselect prompt, or the select prompt when themultiple options is true.

**command****description**
-------------------------------------------------------------------------------------------------------------------------------------
spaceToggle
numberMove
aToggle
iInvert
gToggle

Hide/show choices


**command****description**
-----------------------------------------------------------------------------
fnDecrease
fnIncrease

Move/lock Pointer


**command****description**
------------------------------------------------------------------------------------------------------------------------------------------------------
numberMove
upMove
downMove
ctrlMove
ctrlMove
shiftScroll
shiftScroll

**command**command**description**
---------------------------------------------------------------------------------------------------------------
fnhomeMove
fnendMove

❯ Release History


Please see CHANGELOG.md.

❯ Performance


System specs


MacBook Pro, Intel Core i7, 2.5 GHz, 16 GB.

Load time


Time it takes for the module to load the first time (average of 3 runs):

  1. ```
  2. enquirer: 4.013ms
  3. inquirer: 286.717ms
  4. ```

❯ About


Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Todo


We're currently working on documentation for the following items. Please star and watch the repository for updates!
[ ] Customizing symbols
[ ] Customizing styles (palette)
[ ] Customizing rendered input
[ ] Customizing returned values
[ ] Customizing key bindings
[ ] Question validation
[ ] Choice validation
[ ] Skipping questions
[ ] Async choices
[ ] Async timers: loaders, spinners and other animations
[ ] Links to examples
Running Tests

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:

  1. ```sh
  2. $ npm install && npm test
  3. ```
  1. ```sh
  2. $ yarn && yarn test
  3. ```

Building docs

_(This project's readme.md is generated by [verb](https://github.com/verbose/v