Vorpal

Conquer the command-line.

              (O)
              <M
   o          <M  
  /| ......  /:M\------------------------------------------------,,,,,,
(O)[ vorpal ]::@+}==========================================------------>
  \| ^^^^^^  \:W/------------------------------------------------''''''
   o          <W  
              <W
              (O)

Vorpal is Node's first framework for building interactive CLI applications. With a simple and powerful API, Vorpal opens the door to a new breed of rich, immersive CLI environments like wat and vantage.

Contents

• Introduction
• Getting Started
• API
• Extensions
• FAQ
• License

Introduction

Inspired by and based on commander.js, Vorpal is a framework for building immersive CLI applications built on an interactive prompt provided by inquirer.js. Vorpal launches Node into an isolated CLI environment and provides a suite of API commands and functionality including:

• [x] Simple, powerful command creation
• [x] Supports optional, required and variadic arguments and options
• [x] Piped commands
• [x] Command history
• [x] Built-in help
• [x] Built-in tabbed auto-completion
• [x] Command-specific auto-completion
• [x] Customizable prompts
• [x] Extensive terminal control
• [x] Custom event listeners
• [x] And more!

Vorpal supports community extensions, which empower it to do awesome things such as piping commands to less, importing commands live or even supporting a built-in REPL.

Made with :heart: by dthree.

Getting Started

Quick Start

Install vorpal into your project:

$ npm install vorpal --save

Create a .js file and add the following:

var vorpal = require('vorpal')();

vorpal
  .command('foo', 'Outputs "bar"')
  .action(function(args, callback) {
    this.log('bar');
    callback();
  });

vorpal
  .delimiter('myapp$')
  .show();

This creates an instance of Vorpal, adds a command which logs "bar", sets the prompt delimiter to say "myapp$", and shows the prompt.

Run your project file. Your Node app has become a CLI:

$ node server.js
myapp~$

Try out your "foo" command.

myapp~$ foo
bar
myapp~$

Now type "help" to see Vorpal's built in commands in addition to "foo":

myapp~$ help

  Commands

    help [command]    Provides help for a given command.
    exit [options]    Exits the app.
    foo               Outputs "bar".

myapp~$

That's the basic idea. Once you get the hang of it, read on to learn some of the fancier things Vorpal can do.

Community

• Q&A? Gitter chat
• Stack Overflow
• Vorpal extensions
• Projects made with Vorpal

API

Command

• vorpal.command
• command.description
• command.alias
• command.parse
• command.option
• command.hidden
• command.remove
• command.help
• command.autocompletion
• command.action

Mode

• vorpal.mode
• mode.delimiter
• mode.init
• mode.action

Catch

• vorpal.catch

CommandInstance

• commandInstance.log
• commandInstance.prompt
• commandInstance.delimiter

UI

• ui.delimiter
• ui.input
• ui.imprint
• ui.submit
• ui.cancel
• ui.imprint
• ui.redraw
• ui.redraw.clear
• ui.redraw.done

Vorpal

• .parse
• .delimiter
• .show
• .find
• .exec
• .log
• .pipe
• .use

Events

Extensions

You can build your own Vorpal commands and extensions!

• List of awesome extensions
• Building your own extension

FAQ

• What is an "immersive CLI app?"
• Wasn't this called Vantage?

Why Vorpal?

One, two! One, two! and through and through
The vorpal blade went snicker-snack!
He left it dead, and with its head
He went galumphing back.

Lewis Carroll, Jabberwocky

Life Goals:

• Build a popular framework based on the Jabberwocky poem.

Roadmap

• Suggest something!

License

MIT