Add a CLI to Node Apps with Vantage

2015-06-23 16:59:45 +0100 by Alex R. Young

Vantage (GitHub: dthree/vantage, License: MIT, npm: vantage) by David Caccavella is a very nicely packaged module for adding command-line interfaces to your Node applications. It provides two components: a server, and a command-line tool that you use to connect to your live app. Rather than connecting to a TCP port with something like telnet, you actually type vantage in the command-line.

To hook it up to your application, you'll need to add a Vantage server. First, install Vantage to your project (npm install --save vantage), then instantiate a Vantage object and hook up the functionality that you want:

var Vantage = require('vantage');
var server = new Vantage();

  .description('Outputs "bar".')
  .action(function(args, cb) {
    // Do anything: check the database, run migrations, show useful stats


I'd put this in a separate file to your main Express/Koa/Hapi/etc. app server, then add Vantage actions for the desired functionality. You could add things like database queries, or heartbeat/usage info, and so on.

Once you've added Vantage to your web app, if you install it globally you'll be able to just type vantage ip:port to connect to your server. Typing help will display the built-in commands and any actions that you've added. You should see something like this for the previous example:

webapp~$ help


    help [command]    Provides help for a given command.
    exit [options]    Exists instance of Vantage.
    vantage [server]  Connects to another application running vantage.
    foo               Outputs "bar".

In addition to basic commands and subcommands, Vantage uses inquirer for prompts. Inquirer's prompts are quite powerful: they're ideal for things like yes/no questions and checkboxes. You could use it to force a "yes/no" prompt before a irreversible operation.

Vantage has a few other nice features that'll make your backdoor feel more professional: you can add a banner when people sign in (perhaps with legal warnings, or help), it supports a "firewall" for limiting access, and the documentation has details for using Vantage with Express, Koa, and TLS/SSL.

On the subject of backdoors: Vantage doesn't currently support authentication. It may be possible to use it as a limited informational interface to your server, but I'd strongly recommend binding to internal interfaces only. That means you'd have to ssh to a server, and then run vantage remotely. If that's not possible or convenient, then at least set up TLS/SSL. The current idea for authentication is to support it through middleware -- it already supports middleware so actions can be made reusable, so it seems like a sensible approach.

Authentication issues aside, it definitely seems like something worth using for development servers: I know many people who would love to see their Node web apps get the kind of consoles that popular web frameworks offer (Django's manage.py shell and Rails' console are two that spring to mind). Check it out, but try local/development mode first!