prompt
    Overview
    Dependencies
    Versions
    Playground
    Code
    Documentation
    Issues
    Find an Expert
    Career Opportunities
    Alternatives
    Insights & Analysis

prompt

A beautiful command-line prompt for node.js

1.0.0  •  Published 4 years ago  •  by Nodejitsu Inc.  •  MIT License

A beautiful command-line prompt for node.js

Features

  • prompts the user for input
  • supports validation and defaults
  • hides passwords

Usage

Using prompt is relatively straight forward. There are two core methods you should be aware of: prompt.get() and prompt.addProperties(). Their 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 prompt is easy. Lets take a look at examples/simple-prompt.js:

  var prompt = require('prompt');

  //
  // Start the prompt
  //
  prompt.start();

  //
  // Get two properties from the user: username and email
  //
  prompt.get(['username', 'email'], function (err, result) {
    //
    // Log the results.
    //
    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 schema = {
    properties: {
      name: {
        pattern: /^[a-zA-Z\s\-]+$/,
        message: 'Name must be only letters, spaces, or dashes',
        required: true
      },
      password: {
        hidden: true
      }
    }
  };

  //
  // Start the prompt
  //
  prompt.start();

  //
  // Get two properties from the user: email, password
  //
  prompt.get(schema, function (err, result) {
    //
    // Log the results.
    //
    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

prompt understands JSON-schema with a few extra parameters and uses revalidator for validation.

Here’s an overview of the properties that may be used for validation and prompting controls:

  {
    description: 'Enter your password',     // Prompt displayed to the user. If not supplied name will be used.
    type: 'string',                 // Specify the type of input to expect.
    pattern: /^\w+$/,                  // Regular expression that input must be valid against.
    message: 'Password must be letters', // Warning message to display if validation fails.
    hidden: true,                        // If true, characters entered will either not be output to console or will be outputed using the `replace` string.
    replace: '*',                        // If `hidden` is set it will replace each hidden character with the specified string.
    default: 'lamepassword',             // Default value to use if no value is entered.
    required: true                        // If true, value entered must be non-empty.
    before: function(value) { return 'v' + value; } // Runs before node-prompt callbacks. It modifies user's input
  }

Alternatives to pattern include format and conform, as documented in revalidator.

Supported types are string, boolean, number, integer, array

Using type: 'boolean' accepts case insensitive values ‘true’, ‘t’, ‘false’, ‘f’

Using type: 'array' has some special cases.

  • description will not work in the schema if type: 'array' is defined.
  • maxItems takes precedence over minItems.
  • Arrays that do not have maxItems defined will require users to SIGINT (^C) before the array is ended.
  • If SIGINT (^C) is triggered before minItems is met, a validation error will appear. This will require users to SIGEOF (^D) to end the input.

For more information on things such as maxItems and minItems, refer to the revalidator repository.

Alternate Validation API:

Prompt, in addition to iterating over JSON-Schema properties, will also happily iterate over an array of validation objects given an extra ‘name’ property:

  var prompt = require('../lib/prompt');

  //
  // Start the prompt
  //
  prompt.start();

  //
  // Get two properties from the user: username and password
  //
  prompt.get([{
      name: 'username',
      required: true
    }, {
      name: 'password',
      hidden: true,
      conform: function (value) {
        return true;
      }
    }], function (err, result) {
    //
    // Log the results.
    //
    console.log('Command-line input received:');
    console.log('  username: ' + result.username);
    console.log('  password: ' + result.password);
  });

Backward Compatibility

Note that, while this structure is similar to that used by prompt 0.1.x, that the object properties use the same names as in JSON-Schema. prompt 0.2.x is backward compatible with prompt 0.1.x except for asynchronous validation.

Skipping Prompts

Sometimes power users may wish to skip prompts 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.

  //prompt-override.js

  var prompt = require('prompt'),
      optimist = require('optimist')

  //
  // set the overrides
  //
  prompt.override = optimist.argv

  //
  // Start the prompt
  //
  prompt.start();

  //
  // Get two properties from the user: username and email
  //
  prompt.get(['username', 'email'], function (err, result) {
    //
    // Log the results.
    //
    console.log('Command-line input received:');
    console.log('  username: ' + result.username);
    console.log('  email: ' + result.email);
  })

  //: node prompt-override.js --username USER --email EMAIL

It is also possible to skip prompts dynamically based on previous prompts. If an ask method is added, prompt will use it to determine if the prompt should be displayed. If ask returns true the prompt is displayed. otherwise, the default value or empty string are used.

  var schema = {
    properties: {
      proxy: {
        description: 'Proxy url',
      },
      proxyCredentials: {
        description: 'Proxy credentials',
        ask: function() {
          // only ask for proxy credentials if a proxy was set
          return prompt.history('proxy').value > 0;
        }
      }
    }
  };

  //
  // Start the prompt
  //
  prompt.start();

  //
  // Get one or two properties from the user, depending on
  // what the user answered for proxy
  //
  prompt.get(schema, function (err, result) {
    //
    // Log the results.
    //
    console.log('Command-line input received:');
    console.log('  proxy: ' + result.proxy);
    console.log('  credentials: ' + result.proxyCredentials);
  });

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. prompt exposes a convenience method for doing just this:

  var obj = {
    password: 'lamepassword',
    mindset: 'NY'
  }

  //
  // Log the initial object.
  //
  console.log('Initial object to be extended:');
  console.dir(obj);

  //
  // Add two properties to the empty object: username and email
  //
  prompt.addProperties(obj, ['username', 'email'], function (err) {
    //
    // Log the results.
    //
    console.log('Updated object received:');
    console.dir(obj);
  });

Prompt history

You can use the prompt.history() method to get access to previous prompt input.

  prompt.get([{
    name: 'name',
    description: 'Your name',
    type: 'string',
    required: true
  }, {
    name: 'surname',
    description: 'Your surname',
    type: 'string',
    required: true,
    message: 'Please dont use the demo credentials',
    conform: function(surname) {
      var name = prompt.history('name').value;
      return (name !== 'John' || surname !== 'Smith');
    }
  }], function(err, results) {
    console.log(results);
  });

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, prompt supports ANSI color codes via the colors module for custom colors. For a very colorful example:

  var prompt = require("prompt");
  var colors = require("colors/safe");
  //
  // Setting these properties customizes the prompt.
  //
  prompt.message = colors.rainbow("Question!");
  prompt.delimiter = colors.green("><");

  prompt.start();

  prompt.get({
    properties: {
      name: {
        description: colors.magenta("What is your name?")
      }
    }
  }, function (err, result) {
    console.log(colors.cyan("You said your name is: " + result.name));
  });

If you don’t want colors, you can set

var prompt = require('prompt');

prompt.colors = false;

Integration with streamlinejs

When integrating prompt with projects using streamlinejs such as the following

prompt.start();
function test_prompt(_){
    console.log(prompt.get(loadDataValues(), _).output);
}
test_prompt(_);

This will work, however the process is then stuck with a stdin stream still open. If you setup the traditional way (with callback) such as this

prompt.start();
function test_prompt(){
   prompt.get(loadDataValues(), function(err, data){
       console.log(data.output);
   });
}
test_prompt();

This works and ends correctly.

To resolve this we have added a new method to prompt, which will stop the stdin stream

//
// ### function stop ()
// Stops input coming in from stdin
//
prompt.stop = function () {
    if (prompt.stopped || !prompt.started) {
        return;
    }

    stdin.destroy();
    prompt.emit('stop');
    prompt.stopped = true;
    prompt.started = false;
    prompt.paused = false;
    return prompt;
}

And you can find an example in the example folder examples/prompt-streamline.js

/*
 * prompt-streamline._js: Example of how to use prompt with streamlinejs.
 *
 * calling syntax: _node prompt-streamline._js
 *
 */
var prompt = require('../lib/prompt');

function getSampleData(){
    return [
        {
            name: 'username',
            message: 'Enter a username'
        }
    ];
};

//
// Start the prompt
//
prompt.start();

function get_username_prompt(_){
    console.log(prompt.get(getSampleData(), _).username);
}

get_username_prompt(_);

//
// Clean the prompt
//
prompt.stop();

Installation

  $ [sudo] npm install prompt

Running tests

  $ npm test

License: MIT

Author: Charlie Robbins

Contributors: Josh Holbrook, Pavan Kumar Sunkara

Dependencies

colors  ·  pkginfo  ·  read  ·  revalidator  ·  utile  ·  winston  ·  vows
Keep your dependencies fresh!
Upgrade your packages safely and continuously.
We run your CI tests and compatability tests on new versions of your packages - to determine which upgrades are safe
Just $9/month per developer

Popularity

Weekly Downloads
551.1K
Stars
1.5K

Issues and PRs

Activity

Last ver 4 years ago
Created 8 years ago
Last commit 2 years ago
8 days between commits

Sustainability

48 contributors

Technology

Node version: 4.2.2
0 unpacked

Legal and Compliance

MIT License
OSI Approved
0 vulnerabilities

Top Experts

indexzero
Maintainer, 66 commits, 7 merges, 1 PRs
Works at GoDaddy
Gangstead
Maintainer, 34 commits, 21 merges, 7 PRs
Works at Twitter Gangstead
Joshua Holbrook
35 commits, 1 merges, 2 PRs
Works at Fusion Media Group
Pavan Kumar Sunkara
27 commits, 4 merges
Works at apiaryio
Jarrett Cruger
Maintainer, 15 commits, 4 merges
Works at GoDaddy Inc.
Maciej Małecki
11 commits, 1 merges, 1 PRs