Lightweight and without any external dependencies promptable enables you to receive various types of user input through a set of intuitive, interactive & verbose command-line prompts. The library utilizes a simple & minimal usage syntax and contains 7 configurable console interfaces, such as plain text, confirmation & password/secret prompts as well as single keypress, quiz & multiple-choice navigable menus.
You can now support the development process by donating on Open Collective.
Visit the contributing guidelines to learn more on how to translate this document into more languages.
yarn add promptable
npm install promptable
Import promptable and start using any of the available prompts:
confirmhiddeninputinteractivekeypressquizsecureIn order to sequentially create & display a series of prompts, the asynchronous unary promptable.prompt function can be used. The function accepts as input an array of objects, where each object contains the configuration of its corresponding prompt. The display order of the prompts is based on the order in which the configuration objects are defined inside the array. A new object containing the user's response to each prompt is finally returned by the function.
const promptable = require('promptable');
const {log} = console;
const ps = [
{
type: 'input',
query: 'Type your username:',
handle: 'username'
},
{
type: 'secure',
query: 'Type your password:',
handle: 'password'
}
];
promptable.prompt(ps).then(log);
//=> { username: 'voidcharm', password: 'token' }
Alternatively, for non sequential use-cases, each prompt can be individually initialized through its respective asynchronous unary function, where each function accepts as input an object containing the prompt's properties/configuration.
const promptable = require('promptable');
const {log} = console;
const login = async () => {
const username = await promptable.input({
query: 'Type your username:',
handle: 'username'
});
const password = await promptable.secure({
query: 'Type your password:',
handle: 'password'
});
return Object.assign({}, username, password);
}
login().then(log);
//=> { username: 'voidcharm', password: 'token' }
Initializes a text based input prompt with two accept & deny options. Based on the input provided by the user, the query displayed by the prompt is confirmed or rejected. In order for the query to be confirmed, thus return true, the user must provide exactly the indicated accept string (strict equality). On any other input the query is rejected & false is returned. The return value is a new object with the prompt result stored under the specified handle property.
const promptable = require('promptable');
const {log} = console;
const confirm = {
type: 'confirm',
query: 'Update Promptable to latest version?',
handle: 'update',
accept: 'Y',
deny: 'n'
};
// using the `prompt` async method
promptable.prompt([confirm]).then(log);
//=> { update: true }
// using the `confirm` async method
promptable.confirm(confirm).then(log);
//=> { update: true }
Initializes a text based prompt, where each character typed by the user is automatically hidden. The return value is a new object with the prompt result stored under the specified handle property.
const promptable = require('promptable');
const {log} = console;
const hidden = {
type: 'hidden',
query: '[sudo] password for admin:',
handle: 'sudo'
};
// using the `prompt` async method
promptable.prompt([hidden]).then(log);
//=> { sudo: 'admin' }
// using the `hidden` async method
promptable.hidden(hidden).then(log);
//=> { sudo: 'admin' }
Initializes a text based prompt, where input can be freely provided by the user. The return value is a new object with the prompt result stored under the specified handle property.
const promptable = require('promptable');
const {log} = console;
const input = {
type: 'input',
query: 'Select your username:',
handle: 'username'
};
// using the `prompt` async method
promptable.prompt([input]).then(log);
//=> { username: 'voidcharm' }
// using the `input` async method
promptable.input(input).then(log);
//=> { username: 'voidcharm' }
Initializes an interactive navigable menu based prompt, where the user can navigate within a set of options and select only one of them. The options can be defined in the menu array while the navigation indicator can be customized through the symbol option and if omitted the default string '>' will be used. The return value is new object with the selected option stored under the specified handle property. The interactive menu can be navigated through the up arrow/k & down arrow/j keys.
const promptable = require('promptable');
const {log} = console;
const interactive = {
type: 'interactive',
query: 'What is your favorite treat?',
handle: 'treat',
symbol: '>',
menu: [
'Chocolate',
'Cupcakes',
'Ice-Cream'
]
};
// using the `prompt` async method
promptable.prompt([interactive]).then(log);
//=> { treat: 'Cupcakes' }
// using the `interactive` async method
promptable.interactive(interactive).then(log);
//=> { treat: 'Cupcakes' }
Initializes an non-navigable menu based prompt, where the user can select one of the options defined in the menu array, by pressing the unique key corresponding to it. The options can be up to 9, and the keys are integers x where 1 <= x <= 9. The return value is new object with the selected option stored under the specified handle property.
const promptable = require('promptable');
const {log} = console;
const keypress = {
type: 'keypress',
query: 'How useful are the new features?',
handle: 'features',
menu: [
'Meh',
'Averagely',
'Very',
'Super'
]
};
// using the `prompt` async method
promptable.prompt([keypress]).then(log);
//=> { features: 'Very' }
// using the `keypress` async method
promptable.keypress(keypress).then(log);
//=> { features: 'Very' }
Initializes an interactive navigable menu based prompt, where the user can navigate within a set options and select only one of them. The displayed menu is consisted of a number amount of options, of which the value of answer is by default one of them, corresponding to the correct answer to the query, and the rest amount - 1 are randomly selected from the choices array. The navigation indicator can be customized through the symbol option and if omitted the default string '>' is used. The return value is new object containing the selected option, stored under the specified handle property, and a boolean isCorrect attribute, indicating whether the choice made by the user was the answer one. The quiz menu can be navigated through the up arrow/k & down arrow/j keys.
const promptable = require('promptable');
const {log} = console;
const quiz = {
type: 'quiz',
query: 'How far is the moon from Earth?',
handle: 'distance',
answer: '333400 km',
symbol: '>',
amount: 4,
choices: [
'190000 km',
'280500 km',
'333400 km',
'560000 km',
'890500 km'
]
};
// using the `prompt` async method
promptable.prompt([quiz]).then(log);
//=> { distance: { answer: '333400 km', isCorrect: true } }
// using the `quiz` async method
promptable.quiz(quiz).then(log);
//=> { distance: { answer: '333400 km', isCorrect: true } }
Initializes a text based prompt, where each character typed by the user is automatically replaced with the * symbol. The return value is an object with the prompt result stored under the specified handle property.
const promptable = require('promptable');
const {log} = console;
const secure = {
type: 'secure',
query: 'What\'s your password:',
handle: 'password'
};
// using the `prompt` async method
promptable.prompt([secure]).then(log);
//=> { password: 'password' }
// using the `secure` async method
promptable.secure(secure).then(log);
//=> { password: 'password' }
Promptable can be collectively configured through the unary promptable.config() function, which accepts an object containing the following two attributes: prefix & underlineQuery. The configuration is applied to all prompts belonging to the targeted promptable instance.
prefixString''A string to be included as prefix to the query of each prompt.
underlineQueryBooleanfalseUnderline the query of each prompt.
const promptable = require('promptable');
promptable.config({
prefix: '>', // Use the `>` string as prefix to all queries
underlineQuery: false // Do not underline queries
})
promptable.secure({
type: 'secure',
query: 'Type your password:',
handle: 'password'
});
//=> > Type your password: ******
Additionally, for individual customization the unary prefix & underlineQuery functions are available.
const promptable = require('promptable');
// Use the `>` string as prefix to all queries
promptable.prefix('>');
// Do not underline queries
promptable.underlineQuery(false);
promptable.secure({
type: 'secure',
query: 'Type your password:',
handle: 'password'
});
//=> > Type your password: ******
prompt([, configObj])FunctionTrueObjectSequentially create & display a series of prompts.
configObjObjectObject containing the configuration of a prompt. Can hold any of the documented options.
confirm({ type, query, handle, accept, deny })FunctionTrueObjectCreate and display a confirm prompt.
typeString'confirm'Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to promptable.prompt() function. Can be considered optional when it is part of the object passed to the promptable.confirm() function.
queryStringThe query to be displayed by the prompt.
handleStringThe name of the attribute under which the prompt result will be saved, inside the returned object.
acceptString'Y'The string to be typed in order for the prompt to be confirmed.
denyString'n'The string to be typed in order for the prompt to be rejected.
hidden({ type, query, handle })FunctionTrueObjectCreate and display a hidden prompt.
typeString'hidden'Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to promptable.prompt() function. Can be considered optional when it is part of the object passed to the promptable.hidden() function.
queryStringThe query to be displayed by the prompt.
handleStringThe name of the attribute under which the prompt result will be saved, inside the returned object.
input({ type, query, handle })FunctionTrueObjectCreate and display an input prompt.
typeString'input'Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to promptable.prompt() function. Can be considered optional when it is part of the object passed to the promptable.input() function.
queryStringThe query to be displayed by the prompt.
handleStringThe name of the attribute under which the prompt result will be saved, inside the returned object.
interactive({ type, query, handle, symbol, menu })FunctionTrueObjectCreate and display an interactive prompt.
typeString'interactive'Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to promptable.prompt() function. Can be considered optional when it is part of the object passed to the promptable.interactive() function.
queryStringThe query to be displayed by the prompt.
handleStringThe name of the attribute under which the prompt result will be saved, inside the returned object.
symbolString'>'The string to be used as the navigation indicator for the menu. can be customized through the symbol option and if omitted the default string '>' will be used.
menuString[]The array containing the menu options.
keypress({ type, query, handle, menu })FunctionTrueObjectCreate and display a keypress prompt.
typeString'keypress'Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to promptable.prompt() function. Can be considered optional when it is part of the object passed to the promptable.keypress() function.
queryStringThe query to be displayed by the prompt.
handleStringThe name of the attribute under which the prompt result will be saved, inside the returned object.
menuString[]The array containing the menu options.
quiz({ type, query, handle, answer, symbol, amount, choices })FunctionTrueObjectCreate and display a quiz prompt.
typeString'quiz'Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to promptable.prompt() function. Can be considered optional when it is part of the object passed to the promptable.quiz() function.
queryStringThe query to be displayed by the prompt.
handleStringThe name of the attribute under which the prompt result will be saved, inside the returned object.
answerStringThe correct answer to the quiz.
symbolString'>'The string to be used as the navigation indicator for the menu.
amountNumber3The number of options to be included to the menu.
choicesString[]The array containing the candidate menu options.
secure({ type, query, handle })FunctionTrueObjectCreate and display a secure prompt.
typeString'secure'Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to promptable.prompt() function. Can be considered optional when it is part of the object passed to the promptable.secure() function.
queryStringThe query to be displayed by the prompt.
handleStringThe name of the attribute under which the prompt result will be saved, inside the returned object.
config({ prefix, underlineQuery })FunctionFalseCollectively configure a promptable instance.
prefixString''A string to be included as prefix to the query of each prompt.
underlineQueryBooleanfalseUnderline the query of each prompt.
prefix(str)FunctionFalseAdd a string as prefix to the query of each prompt belonging to the targeted promptable instance.
strStringA string to be included as prefix to the query of each prompt.
underlineQuery(status)FunctionFalseUnderline the query of each prompt belonging to the targeted promptable instance.
statusBooleanUnderline the query of each prompt.
clearScreen()FunctionFalseMove the cursor to the top-left corner of the console and clear everything below it.
For more info on how to contribute to the project, please read the contributing guidelines.
cd promptablenpm install or yarn installnpm test or yarn testFAQs
Minimal interactive command-line prompts
We found that promtable demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.