{"id":11589,"library":"promptly","title":"Promptly CLI Utility","description":"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.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/moxystudio/node-promptly","tags":["javascript","prompt","choose","choice","cli","command","line"],"install":[{"cmd":"npm install promptly","lang":"bash","label":"npm"},{"cmd":"yarn add promptly","lang":"bash","label":"yarn"},{"cmd":"pnpm add promptly","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import promptly from 'promptly';","symbol":"promptly","correct":"const promptly = require('promptly');"},{"note":"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.","wrong":"import { prompt } from 'promptly';","symbol":"prompt","correct":"const { prompt } = require('promptly');"},{"note":"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`.","wrong":"promptly.prompt('Name: ').then(name => console.log(name));","symbol":"Async/Await usage","correct":"(async () => { const name = await promptly.prompt('Name: '); console.log(name); })();"}],"quickstart":{"code":"const promptly = require('promptly');\n\nconst validator = function (value) {\n    if (value.length < 2) {\n        throw new Error('Min length of 2');\n    }\n\n    return value;\n};\n\n(async () => {\n    try {\n        console.log('Please enter your name. It must be at least 2 characters long.');\n        // Since retry is true by default, promptly will keep asking for a name until it is valid\n        // Between each prompt, the error message from the validator will be printed\n        const name = await promptly.prompt('Your Name: ', { validator });\n        console.log(`Hello, ${name}!`);\n\n        // Example with silent input (for password)\n        const password = await promptly.prompt('Enter password (will not show): ', { silent: true, replace: '*' });\n        console.log('Password length:', password.length);\n\n    } catch (err) {\n        console.error('An error occurred:', err.message);\n    }\n})();","lang":"javascript","description":"This quickstart demonstrates basic prompting, input validation with custom error messages, and silent input for sensitive information like passwords, utilizing async/await for clarity."},"warnings":[{"fix":"Set `retry: false` in the options object: `promptly.prompt('Message: ', { validator, retry: false })`.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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 })`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your validator function explicitly throws an `Error` instance or a string message when validation fails, e.g., `throw new Error('Validation failed');`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The user did not provide input within the `timeout` duration specified in the options.","error":"Error: timed out"},{"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.","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`).","error":"ReferenceError: require is not defined in ES module scope"},{"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.","cause":"This is a custom error thrown by a user-defined validator function because the input did not meet the specified length requirement.","error":"Error: Min length of 2"}],"ecosystem":"npm"}