<commit_before><h1 align="center">Enquirer</h1>

<br>
<br>

<p align="center">
  <b>Stylish CLI prompts that are user-friendly, intuitive and easy to create.</b></br>
  <sub>>_ Prompts should be more like conversations than inquisitions▌<sub>
</p>

<br>
<br>

Enquirer is fast, easy to use, and lightweighte enough for small projects, while also being powerful and customizable enough for the most advanced use cases. 

- **Fast** - [Loads in ~4ms](#performance) (that's about _3-4 times faster than a [single frame of a HD movie](http://www.endmemo.com/sconvert/framespersecondframespermillisecond.php) at 60fps_)
- **Lightweight** - Only [one dependency](https://github.com/doowb/ansi-colors).
- **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](recipes/play.js) 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.

<br>
<hr>
<br>

## ❯ Install

{%= include("install-npm", { save: true }) %}

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

<br>
<hr>
<br>

## ❯ Getting started

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

- [Usage](#-usage)
- [API](#-api)
- [Options](#-options)
- [Performance](#-performance)
- [Credit](#-credit)

<br>
<hr>
<br>

## ❯ Usage

### Single prompt

Pass a [question object](#prompt-options) to run a single prompt.

```js
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](#prompt-options) to run a series of prompts.

```js
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: '<NAME>', username: 'edwardmchan' }
```

<br>
<hr>
<br>

## ❯ API

### Enquirer API

{%= apidocs("index.js") %}

## Prompt API

{%= apidocs("lib/prompt.js") %}

<br>
<hr>
<br>

## ❯ Options

### Enquirer options

TODO

### Prompt options

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

```js
{
  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**

```js
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

```js
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](https://github.com/derhuerst), creator of prompt libraries such as [prompt-skeleton][], which influenced some of the concepts we used in our prompts.
<commit_msg>add beta release information<commit_after><h1 align="center">Enquirer</h1>

<br>
<br>

<p align="center">
  <b>Stylish CLI prompts that are user-friendly, intuitive and easy to create.</b></br>
  <sub>>_ Prompts should be more like conversations than inquisitions▌<sub>
</p>

<br>
<br>

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](#performance) (that's about _3-4 times faster than a [single frame of a HD movie](http://www.endmemo.com/sconvert/framespersecondframespermillisecond.php) at 60fps_)
- **Lightweight** - Only [one dependency](https://github.com/doowb/ansi-colors).
- **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](recipes/play.js) 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.

<br>
<hr>
<br>

## ❯ Beta release!!!

We're extremely excited to announce that we've published Enquirer 2.0.0 as a beta release to [npm](https://www.npmjs.com/package/enquirer/v/beta). To use the beta version see the [installation instructions below](#-install).

This documentation is for the beta, which means we're still working on documenting everything, creating [examples](./examples), and having fun writing [recipes](./recipes) to demonstrate how [prompts](#prompt-api) can be extended and customized. If you'd like to contribute to any of these, please feel free to open an [issue](./issues/new) for discussion or [pull request](./pulls) 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.

<br>
<hr>
<br>

## ❯ Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save {%= name %}@beta
```

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

<br>
<hr>
<br>

## ❯ Getting started

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

- [Usage](#-usage)
- [API](#-api)
- [Options](#-options)
- [Performance](#-performance)
- [Credit](#-credit)

<br>
<hr>
<br>

## ❯ Usage

### Single prompt

Pass a [question object](#prompt-options) to run a single prompt.

```js
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](#prompt-options) to run a series of prompts.

```js
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: '<NAME>', username: 'edwardmchan' }
```

<br>
<hr>
<br>

## ❯ API

### Enquirer API

{%= apidocs("index.js") %}

## Prompt API

{%= apidocs("lib/prompt.js") %}

<br>
<hr>
<br>

## ❯ Options

### Enquirer options

TODO

### Prompt options

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

```js
{
  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**

```js
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

```js
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](https://github.com/derhuerst), creator of prompt libraries such as [prompt-skeleton][], which influenced some of the concepts we used in our prompts.

{'fraction_non_alphanumeric': 0.1426224378031607, 'fraction_numerical': 0.0070411516194648725, 'mean_word_length': 3.755580357142857, 'pattern_counts': {'":': 0, '<': 64, '<?xml version=': 0, '>': 70, 'https://': 6, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3117926', 'n_tokens_mistral': 4156, 'n_tokens_neox': 3903, 'n_words': 1540}