README.md

Enquirer

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

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.
• Easy to use - Uses promises and async/await to make prompts easy to create and use.
• Intuitive - Navigating around input and choices is a breeze. Advanced keypress combos are available to simplify usage. You can even record and playback keypresses to aid with tutorials and videos.
• Multilingual - Easily add support for multiple languages.
• Extensible - Prompts are easy to create and extend.
• Flexible - All prompts can be used standalone or chained together.
• Pluggable - Add advanced features to Enquirer with plugins.
• Stylish - Easily override styles and symbols for any part of the prompt.
• 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.

❯ Table of Contents

• Install
• Getting started
• Usage
• Enquirer API
• Prompts
• Types
• Keypresses
• Options
• Release History
• Performance
• About

❯ Install

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.)

❯ Getting started

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

• Usage
• Enquirer
• Prompts
• Options
• Release History
• Performance
• Credit

❯ Usage

Single prompt

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

const { prompt } = require('enquirer');

const response = await prompt({
  type: 'input',
  name: 'username',
  message: 'What is your username?' 
});

console.log(response); 
//=> { username: 'jonschlinkert' }

(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.

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' }

❯ 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

const Enquirer = require('enquirer');
const enquirer = new Enquirer();

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

const Enquirer = require('enquirer');
const enquirer = new Enquirer();
enquirer.register('customType', require('./custom-prompt'));

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

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

Use an enquirer plugin.

Params

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

Example

const Enquirer = require('enquirer');
const enquirer = new Enquirer();
const plugin = enquirer => {
  // do stuff to enquire instance
};
enquirer.use(plugin);

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

const { prompt } = require('enquirer');
const response = await prompt({
  type: 'input',
  name: 'username',
  message: 'What is your username?'
});
console.log(response);

❯ Prompts

• AutoComplete
• Confirm
• Input
• Invisible
• List
• Multiselect
• Number
• Password
• Select
• Snippet
• Sort
• Survey
• Text (alias for Input)

AutoComplete Prompt

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

Related prompts

• select prompt
• multiselect prompt
• survey prompt

Confirm Prompt

Prompt that returns true or false.

Related prompts

• input prompt
• number prompt
• password prompt

Input Prompt

Prompt that takes user input and returns a string.

Related prompts

• confirm prompt
• number prompt
• password prompt

Invisible Prompt

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

Related prompts

• password prompt
• input prompt

List Prompt

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

Related prompts

• sort prompt
• select prompt

Multiselect Prompt

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

Related prompts

• select prompt
• autocomplete prompt

Number Prompt

Prompt that takes a number as input.

Related prompts

• input prompt
• confirm prompt

Password Prompt

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

Related prompts

• input prompt
• invisible prompt

Select Prompt

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

Related prompts

• autocomplete prompt
• multiselect prompt

Snippet Prompt

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

Related prompts

• survey prompt
• autocomplete prompt

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.

Related prompts

• list prompt
• select prompt

Survey Prompt

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

Related prompts

• snippet prompt
• select prompt

❯ Types

• ArrayPrompt
• BooleanPrompt
• DatePrompt (Coming Soon!)
• NumberPrompt
• StringPrompt

ArrayPrompt

todo

BooleanPrompt

todo

NumberPrompt

todo

StringPrompt

todo

❯ Keypresses

All prompts

Key combinations that may be used with all prompts.

Move cursor

Key combinations that may be used on prompts that support user input, such as the input prompt, password prompt, and invisible prompt).

Select choices

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

Hide/show choices

Move/lock Pointer

❯ Options

Prompt options

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
}

(type, name and message are required).

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 objects

Choice {
  name: string;
  message: string | undefined;
  value: string | undefined;
  hint: string | undefined;
  disabled: boolean | string | undefined;
}

❯ Release History

Please see CHANGELOG.md.

❯ Performance

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):

enquirer: 4.013ms
inquirer: 286.717ms
prompts: 17.010ms

❯ About

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

Contributors

Author

Jon Schlinkert

• GitHub Profile
• Twitter Profile
• LinkedIn Profile

Credit

Thanks to derhuerst, creator of prompt libraries such as prompt-skeleton, which influenced some of the concepts we used in our prompts.

License

Copyright © 2018, Jon Schlinkert. Released under the MIT License.