Promptly CLI Utility

3.2.0 · active · verified Sun Apr 19

Promptly is a focused Node.js utility for handling command-line input and user interaction. Currently stable at version 3.2.0, it provides a robust `prompt` function with extensive options for input validation, default values, silent input (e.g., for passwords), character replacement, and custom input/output streams. It supports retry logic for failed validations by default and offers timeout functionality. While the release cadence isn't explicitly stated in the provided documentation, its stable 3.x version and continued maintenance on GitHub suggest a steady, albeit perhaps slower, evolution. Its key differentiators lie in its comprehensive validation system with custom error messages and automatic retries, as well as fine-grained control over I/O streams and timeouts, making it suitable for building interactive CLI tools where user input quality is critical. It is primarily used in Node.js environments for CLI applications.

Common errors

```
Error: timed out
```
cause The user did not provide input within the `timeout` duration specified in the options.

fix Handle the `Error('timed out')` within a `try/catch` block or set `useDefaultOnTimeout: true` in the options if a default value should be used instead of throwing an error.
```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use `require()` in an ECMAScript Module (ESM) file (e.g., a `.mjs` file or a file in a package with `"type": "module"` in `package.json`).

fix If `promptly` does not provide an official ESM export for direct `import`, you might need to use a dynamic `import()` or adjust your project to use CommonJS modules where `promptly` is needed. For `promptly`, stick to `const promptly = require('promptly');` in CommonJS contexts.
```
Error: Min length of 2
```
cause This is a custom error thrown by a user-defined validator function because the input did not meet the specified length requirement.

fix The user input needs to satisfy the conditions of the validator. If `retry` is `true` (default), simply re-enter valid input. If `retry` is `false`, the error must be caught and handled in a `try/catch` block.

Warnings

gotcha By default, `promptly` will retry indefinitely if a validator fails. If you want to handle validation errors yourself after a single attempt, you must explicitly set the `retry` option to `false`.
Fix: Set `retry: false` in the options object: `promptly.prompt('Message: ', { validator, retry: false })`.
gotcha When using the `timeout` option, if the user does not provide input within the specified time, `promptly` will throw an `Error('timed out')`. It does not return `null` or the default value automatically unless `useDefaultOnTimeout` is set.
Fix: Wrap calls with `timeout` in a `try/catch` block to handle the `Error('timed out')`. Alternatively, set `useDefaultOnTimeout: true` to return the `default` value if a timeout occurs: `promptly.prompt('Message: ', { timeout: 3000, default: 'Guest', useDefaultOnTimeout: true })`.
gotcha Validator functions must throw an `Error` object (or a string which promptly wraps in an Error) to indicate failure. Returning `false` or any other non-Error value will not trigger a validation failure.
Fix: Ensure your validator function explicitly throws an `Error` instance or a string message when validation fails, e.g., `throw new Error('Validation failed');`.

Install

npm install promptly npm
yarn add promptly yarn
pnpm add promptly pnpm

Imports

promptly
wrong:
```
import promptly from 'promptly';
```
correct:
```
const promptly = require('promptly');
```
The library primarily uses CommonJS `require()` as shown in documentation examples. While Node.js supports ESM, `promptly` as a whole might not be directly importable as a default ESM export in all environments without bundler configuration. Use `require` for full compatibility with v3.x.
prompt
wrong:
```
import { prompt } from 'promptly';
```
correct:
```
const { prompt } = require('promptly');
```
While `prompt` is the main function, it's typically accessed as a property of the `promptly` module. Direct named import might not work reliably depending on ESM support in the package's build. Stick to destructuring from the `require`'d module.
Async/Await usage
wrong:
```
promptly.prompt('Name: ').then(name => console.log(name));
```
correct:
```
(async () => { const name = await promptly.prompt('Name: '); console.log(name); })();
```
Although `.then()` works, `promptly` functions return Promises, making them ideal for use with `async/await` for cleaner, more synchronous-looking code, especially when chaining multiple prompts or handling errors with `try/catch`.

Quickstart

This quickstart demonstrates basic prompting, input validation with custom error messages, and silent input for sensitive information like passwords, utilizing async/await for clarity.

const promptly = require('promptly');

const validator = function (value) {
    if (value.length < 2) {
        throw new Error('Min length of 2');
    }

    return value;
};

(async () => {
    try {
        console.log('Please enter your name. It must be at least 2 characters long.');
        // Since retry is true by default, promptly will keep asking for a name until it is valid
        // Between each prompt, the error message from the validator will be printed
        const name = await promptly.prompt('Your Name: ', { validator });
        console.log(`Hello, ${name}!`);

        // Example with silent input (for password)
        const password = await promptly.prompt('Enter password (will not show): ', { silent: true, replace: '*' });
        console.log('Password length:', password.length);

    } catch (err) {
        console.error('An error occurred:', err.message);
    }
})();

view raw JSON →