enquirer

Stylish, intuitive and user-friendly prompt system. Fast and lightweight enough for small projects, powerful and extensible enough for the most advanced use cases.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

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.

❯ Beta release!!!

We're extremely excited to announce that we've published Enquirer 2.0.0 as a beta release to npm. To use the beta version see the installation instructions below.

This documentation is for the beta, which means we're still working on documenting everything, creating examples, and having fun writing recipes to demonstrate how prompts can be extended and customized. If you'd like to contribute to any of these, please feel free to open an issue for discussion or pull request with your changes. We are also looking for technical writers to help with writing more detailed user and developer documentation, tutorials, and blog posts about Enquirer 2 and all of the awesome features that are available.

❯ Install

Install with npm:

$ npm install --save enquirer@beta

(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
API
Options
Performance
Credit

❯ Usage

Single prompt

Pass a question object to run a single prompt.

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

❯ 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

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();

(async() => {
  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);

use

Programmatically cancel all prompts.

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();

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');
(async() => {
  const response = await prompt({
    type: 'input',
    name: 'username',
    message: 'What is your username?'
  });
  console.log(response);
})();

Prompt API

❯ Options

Enquirer options

TODO

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,
  answer: function | async function,
  validate: function | async function
}

Property	Type	Description
`type` (required)	`string`, `function`	Enquirer uses this value to determine the type of prompt to run, but it's optional when prompts are run directly.
`name` (required)	`string`, `function`	Used as the key for the answer on the returned values (answers) object.
`message` (required)	`string`, `function`	The message to display when the prompt is rendered in the terminal.
`initial` (optional)	`string`, `function`	The default value to return if the user does not supply a value.
`format` (optional)	`function`	Function to format user input in the terminal.
`result` (optional)	`function`	Function to format the final, submitted value before it's returned.
`validate` (optional)	`function`	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.

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;
  enabled: boolean | undefined;
}

Property	Type	Description
`name`	`string`	The unique id for a choice
`message`	`string`	The message to display
`value`	`string`	The value to return if the choice is selected
`alias`	`string`	Single character to use when keypress shortcuts are supported
`hint`	`string`
`error`	`string`
`disabled`	`boolean`
`separator`	`boolean`
`selected`	`boolean`

❯ 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

❯ Credit

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

About

<summary>Contributing</summary>

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

<summary>Running Tests</summary>

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

<summary>Building docs</summary>

(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

Commits	Contributor
72	jonschlinkert
12	doowb
1	mischah
1	skellock

Author

Jon Schlinkert

License

This file was generated by verb-generate-readme, v0.8.0, on October 30, 2018.

Current Tags

2.0.1 ... beta (6 years ago)
1.0.0 ... beta1 (7 years ago)
2.4.1 ... latest (a year ago)

enquirer

Enquirer

❯ Beta release!!!

❯ Install

❯ Getting started

❯ Usage

Single prompt

Multiple prompts

❯ API

Enquirer

register

prompt

use

use

Enquirer#prompt

Prompt API

❯ Options

Enquirer options

Prompt options

Choice objects

❯ Performance

Load time

❯ Credit

About

Contributors

Author

License

Current Tags

37 Versions