Vorpal








> Conquer the command-line.

``text
(O)
o /| ...... /:M\------------------------------------------------,,,,,,
(O)[ vorpal ]::@+}==========================================------------>
\| ^^^^^^ \:W/------------------------------------------------''''''
o (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 cash and wat.

Notice

This is now an OPEN Open Source project. I am not able to invest a significant amount of time into maintaining Vorpal and so am looking for volunteers who would like to be active maintainers of the project. If you are interested, shoot me a note.

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] Persistent 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 supporting a built-in REPL.

Made with :heart: by dthree.

Getting Started

##### Quick Start

Install vorpal into your project:

`bash
$ npm install vorpal --save
`

Create a .js file and add the following:

`js
const 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:

`bash
$ node server.js
myapp~$
`

Try out your "foo" command.

`bash
myapp~$ foo
bar
myapp~$
`

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

`bash
myapp~$ help

Commands

help [command] Provides help for a given command.
exit [options] Exits instance of Vorpal.
foo Outputs "bar".

myapp~$
`

There's the basics. Once you get the hang of it, follow this tutorial or read on to learn what else Vorpal can do.

##### Community

Questions? Use the vorpal.js StackOverflow tag for fast answers that help others, or jump into chat on Gitter.

- Stack Overflow
- Gitter Chat
- Vorpal extensions
- Projects made with Vorpal
- Follow @vorpaljs

API

##### Command
- vorpal.command
- command.description
- command.alias
- command.parse
- command.option
- command.hidden
- command.remove
- command.help
- command.autocomplete
- command.action
- command.cancel

##### 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
- .execSync
- .log
- .history
- .localStorage
- .help
- .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?

`text
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.

License

MIT © David Caccavella