# vorpal

> Node's first framework for building immersive CLI apps.

Latest version **1.12.0** (published 2017-04-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install vorpal
pnpm add vorpal
yarn add vorpal
bun add vorpal
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.12.0 |
| Published | 2017-04-09 |
| First published | 2015-08-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/vorpal) |
| Module format | CommonJS |
| Node | >= 0.10.0 |
| Dependencies | 10 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5625 |
| Author | dthree |
| Maintainers | dthree, scotthovestadt |
| Keywords | api, cli, repl, shell, immersive, framework, app, application, command, commander, automated, prompt, inquirer |

## Links

- npm: https://www.npmjs.com/package/vorpal
- Repository: https://github.com/dthree/vorpal
- Homepage: https://github.com/dthree/vorpal#readme
- Issues: https://github.com/dthree/vorpal/issues
- npm.io page: https://npm.io/package/vorpal

## Dependencies (10)

- [chalk](https://npm.io/package/chalk.md) ^1.1.0
- [lodash](https://npm.io/package/lodash.md) ^4.5.1
- [inquirer](https://npm.io/package/inquirer.md) 0.11.0
- [minimist](https://npm.io/package/minimist.md) ^1.2.0
- [wrap-ansi](https://npm.io/package/wrap-ansi.md) ^2.0.0
- [in-publish](https://npm.io/package/in-publish.md) ^2.0.0
- [log-update](https://npm.io/package/log-update.md) ^1.0.2
- [strip-ansi](https://npm.io/package/strip-ansi.md) ^3.0.0
- [babel-polyfill](https://npm.io/package/babel-polyfill.md) ^6.3.14
- [node-localstorage](https://npm.io/package/node-localstorage.md) ^0.6.0

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 1.12.0 (latest) — 2017-04-09
- 1.11.4 — 2016-08-05
- 1.11.3 — 2016-08-02
- 1.11.2 — 2016-06-07
- 1.11.1 — 2016-06-02
- 1.11.0 — 2016-06-02
- 1.10.10 — 2016-03-27
- 1.10.9 — 2016-03-23
- 1.10.8 — 2016-03-02
- 1.10.7 — 2016-03-02
- 1.10.6 — 2016-03-02
- 1.10.5 — 2016-03-02
- 1.10.4 — 2016-03-02
- 1.10.3 — 2016-03-02
- 1.10.2 — 2016-03-02
- … 102 more at https://npm.io/package/vorpal/versions

## README

# Vorpal


[![Build Status](https://travis-ci.org/dthree/vorpal.svg)](https://travis-ci.org/dthree/vorpal/)
<a href="https://www.npmjs.com/package/vorpal">
  <img src="https://img.shields.io/npm/dt/vorpal.svg" alt="NPM Downloads" />
</a>
[![Package Quality](http://npm.packagequality.com/shield/vorpal.svg)](http://packagequality.com/#?package=vorpal)
<a href="https://www.npmjs.com/package/vorpal">
  <img src="https://img.shields.io/npm/v/vorpal.svg" alt="NPM Version" />
</a>
[![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)

> Conquer the command-line.

```text
              (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 [cash](https://github.com/dthree/cash) and [wat](https://github.com/dthree/wat).

## Notice

This is now an [OPEN Open Source](http://openopensource.org/) 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](#introduction)
* [Getting Started](#getting-started)
* [API](#api)
* [Extensions](#extensions)
* [FAQ](#faq)
* [License](#license)

## Introduction

Inspired by and based on [commander.js](https://www.npmjs.com/package/commander), Vorpal is a framework for building immersive CLI applications built on an interactive prompt provided by [inquirer.js](https://www.npmjs.com/package/inquirer). 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](https://github.com/vorpaljs/awesome-vorpaljs), which empower it to do awesome things such as [piping commands to less](https://github.com/vorpaljs/vorpal-less), [importing commands live](https://github.com/vorpaljs/vorpal-use) or supporting a [built-in REPL](https://github.com/vorpaljs/vorpal-repl).

Made with :heart: by [dthree](https://github.com/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](http://developer.telerik.com/featured/creating-node-js-command-line-utilities-improve-workflow/) 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](http://stackoverflow.com/questions/tagged/vorpal.js) 
- [Gitter Chat](https://gitter.im/dthree/vorpal?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) 
- [Vorpal extensions](https://github.com/vorpaljs/awesome-vorpaljs#vorpal-extensions) 
- [Projects made with Vorpal](https://github.com/vorpaljs/awesome-vorpaljs) 
- [Follow @vorpaljs](https://twitter.com/vorpaljs) 

## [API](https://github.com/dthree/vorpal/wiki)

##### [Command](https://github.com/dthree/vorpal/wiki/api-|-vorpal.command)
- [`vorpal.command`](https://github.com/dthree/vorpal/wiki/api-%7C-vorpal.command#vorpalcommandcommand-description)
- [`command.description`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.command#commanddescriptionstring)
- [`command.alias`](https://github.com/dthree/vorpal/wiki/api-%7C-vorpal.command#commandaliasname-names)
- [`command.parse`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.command#commandparseparsefunction)
- [`command.option`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.command#commandoptionstring-description)
- [`command.hidden`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.command#commandhidden)
- [`command.remove`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.command#commandremove)
- [`command.help`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.command#commandhelp)
- [`command.autocomplete`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.command#commandautocompletearray-or-object-or-function)
- [`command.action`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.command#commandactionfunction)
- [`command.cancel`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.command#commandcancelfunction)

##### [Mode](https://github.com/dthree/vorpal/wiki/API-|-vorpal.mode)
- [`vorpal.mode`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal.mode#vorpalmodecommand-description)
- [`mode.delimiter`](https://github.com/dthree/vorpal/wiki/API-|-vorpal.mode#modedelimiterstring)
- [`mode.init`](https://github.com/dthree/vorpal/wiki/API-|-vorpal.mode#modeinitfunction)
- [`mode.action`](https://github.com/dthree/vorpal/wiki/API-|-vorpal.mode#modeactionfunction)

##### [Catch](https://github.com/dthree/vorpal/wiki/API-|-vorpal.catch)
- [`vorpal.catch`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal.catch#catchcommand-description)

##### [CommandInstance](https://github.com/dthree/vorpal/wiki/API-|-CommandInstance)
- [`commandInstance.log`](https://github.com/dthree/vorpal/wiki/API-%7C-CommandInstance#commandinstancelogstring-strings)
- [`commandInstance.prompt`](https://github.com/dthree/vorpal/wiki/API-%7C-CommandInstance#commandinstancepromptobject-callback)
- [`commandInstance.delimiter`](https://github.com/dthree/vorpal/wiki/API-%7C-CommandInstance#commandinstancedelimiterstring)

##### [UI](https://github.com/dthree/vorpal/wiki/api-|-vorpal.ui)
- [`ui.delimiter`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.ui#uidelimitertext)
- [`ui.input`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.ui#uiinputtext)
- [`ui.imprint`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.ui#uiimprint)
- [`ui.submit`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.ui#uisubmittext)
- [`ui.cancel`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.ui#uicancel)
- [`ui.imprint`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.ui#uiimprint)
- [`ui.redraw`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.ui#uiredrawtext-text)
- [`ui.redraw.clear`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.ui#uiredrawclear)
- [`ui.redraw.done`](https://github.com/dthree/vorpal/wiki/api-|-vorpal.ui#uiredrawdone)

##### [Vorpal](https://github.com/dthree/vorpal/wiki/API-|-vorpal)
- [`.parse`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpalparseargv-options)
- [`.delimiter`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpaldelimiterstring)
- [`.show`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpalshow)
- [`.find`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpalfindstring)
- [`.exec`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpalexeccommand-callback)
- [`.execSync`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpalexecsynccommand-options)
- [`.log`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpallogstring-strings)
- [`.history`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpalhistoryid)
- [`.localStorage`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpallocalstorageid)
- [`.help`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpalhelpfunction)
- [`.pipe`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpalpipefunction)
- [`.use`](https://github.com/dthree/vorpal/wiki/API-%7C-vorpal#vorpaluseextension)

##### [Events](https://github.com/dthree/vorpal/wiki/Docs-%7C-Events)


## Extensions

You can build your own Vorpal commands and extensions.

- [List of awesome extensions](https://github.com/vorpaljs/awesome-vorpaljs#vorpal-extensions)
- [Building your own extension](https://github.com/dthree/vorpal/wiki/Docs-%7C-Creating-Extensions)


## [FAQ](https://github.com/dthree/vorpal/wiki/FAQ)

- [What is an "immersive CLI app?"](https://github.com/dthree/vorpal/wiki/FAQ#what-is-an-immersive-cli-app)
- [Wasn't this called Vantage?](https://github.com/dthree/vorpal/wiki/FAQ#uh-wasnt-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:

- <s>Build a popular framework based on the [Jabberwocky](https://en.wikipedia.org/wiki/Jabberwocky) poem.</s>


## License

MIT © [David Caccavella](https://github.com/dthree)

---
_Source: https://npm.io/package/vorpal · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._