node-prompt
A beautiful command-line prompt for node.js
Features
- prompts the user for input
- supports validation and defaults
- hides passwords
Installation
Installing npm (node package manager)
curl http://npmjs.org/install.sh | sh
Installing prompt
[sudo] npm install prompt
Usage
Using node-prompt is relatively straight forward. There are two core methods you should be aware of: prompt.get()
and prompt.addProperties()
. There methods take strings representing property names in addition to objects for complex property validation (and more). There are a number of examples that you should examine for detailed usage.
Getting Basic Prompt Information
Getting started with node-prompt
is easy. Lets take a look at examples/simple-prompt.js
:
var prompt = require('prompt');
prompt.start();
prompt.get(['username', 'email'], function (err, result) {
console.log('Command-line input received:');
console.log(' username: ' + result.username);
console.log(' email: ' + result.email);
})
This will result in the following command-line output:
$ node examples/simple-prompt.js
prompt: username: some-user
prompt: email: some-user@some-place.org
Command-line input received:
username: some-user
email: some-user@some-place.org
Prompting with Validation, Default Values, and More (Complex Properties)
In addition to prompting the user with simple string prompts, there is a robust API for getting and validating complex information from a command-line prompt. Here's a quick sample:
var properties = [
{
name: 'name',
validator: /^[a-zA-Z\s\-]+$/,
warning: 'Name must be only letters, spaces, or dashes',
empty: false
},
{
name: 'password',
hidden: true
}
];
prompt.start();
prompt.get(properties, function (err, result) {
console.log('Command-line input received:');
console.log(' name: ' + result.name);
console.log(' password: ' + result.password);
});
Pretty easy right? The output from the above script is:
$ node examples/property-prompt.js
prompt: name: nodejitsu000
error: Invalid input for name
error: Name must be only letters, spaces, or dashes
prompt: name: Nodejitsu Inc
prompt: password:
Command-line input received:
name: Nodejitsu Inc
password: some-password
Valid Property Settings
node-prompt
uses a simple property system for performing a couple of basic validation operations against input received from the command-line. The motivations here were speed and simplicity of implementation to integration of pseudo-standards like JSON-Schema were not feasible.
Lets examine the anatomy of a prompt property:
{
message: 'Enter your password',
name: 'password'
validator: /^\w+$/
warning: 'Password must be letters'
hidden: true
default: 'lamepassword'
empty: false
}
skipping prompts
Sometimes power users may wish to skip promts and specify all data as command line options.
if a value is set as a property of prompt.override
prompt will use that instead of
prompting the user.
var prompt = require('prompt'),
optimist = require('optimist')
prompt.override = optimist.argv
prompt.start();
prompt.get(['username', 'email'], function (err, result) {
console.log('Command-line input received:');
console.log(' username: ' + result.username);
console.log(' email: ' + result.email);
})
Adding Properties to an Object
A common use-case for prompting users for data from the command-line is to extend or create a configuration object that is passed onto the entry-point method for your CLI tool. node-prompt
exposes a convenience method for doing just this:
var obj = {
password: 'lamepassword',
mindset: 'NY'
}
console.log('Initial object to be extended:');
console.dir(obj);
prompt.addProperties(obj, ['username', 'email'], function (err) {
console.log('Updated object received:');
console.dir(obj);
});
Customizing your prompt
Aside from changing property.message
, you can also change prompt.message
and prompt.delimiter
to change the appearance of your prompt.
The basic structure of a prompt is this:
prompt.message + prompt.delimiter + property.message + prompt.delimiter;
The default prompt.message
is "prompt," the default prompt.delimiter
is
": ", and the default property.message
is property.name
.
Changing these allows you to customize the appearance of your prompts! In
addition, node-prompt supports ANSI color codes via the
colors module for custom colors. For a
very colorful example:
var prompt = require("prompt");
require("colors");
prompt.message = "Question!".rainbow;
prompt.delimiter = "><".green;
prompt.start();
prompt.get([{ name: "name",
message: "What is your name?".magenta }], function (err, result) {
console.log("You said your name is: ".cyan + result.name.cyan);
});
Running tests
vows test/*-test.js --spec