CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-vorpal

Node's first framework for building immersive CLI apps.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Vorpal

Vorpal is a comprehensive framework for building interactive command-line interface applications in Node.js. It provides a rich API for creating immersive CLI environments with features like command creation, argument parsing, auto-completion, command history, and extensibility through plugins. The library transforms Node applications into interactive CLI tools with support for complex command structures, piped commands, customizable prompts, and built-in help systems.

Package Information

  • Package Name: vorpal
  • Package Type: npm
  • Language: JavaScript (ES6 with Babel)
  • Installation: npm install vorpal

Core Imports

const Vorpal = require('vorpal');

For ES6/TypeScript environments:

import Vorpal from 'vorpal';

Basic Usage

const vorpal = require('vorpal')();

// Create a command
vorpal
  .command('hello [name]', 'Outputs a greeting')
  .action(function(args, callback) {
    this.log(`Hello, ${args.name || 'World'}!`);
    callback();
  });

// Start the interactive CLI
vorpal
  .delimiter('myapp$')
  .show();

Architecture

Vorpal is built around several key components:

  • Vorpal Instance: Main application controller managing commands, sessions, and UI
  • Command System: Registration, parsing, validation, and execution of CLI commands
  • Session Management: User session handling with local and remote support
  • UI Layer: Terminal interface with prompt rendering, history, and autocomplete
  • Extension System: Plugin architecture for extending functionality with modules
  • Event System: Rich event emission for hooks, intercepts, and custom behaviors

Capabilities

Application Configuration

Core configuration methods for setting up your CLI application including version, title, description, and prompt delimiter.

function version(version: string): Vorpal;
function title(title: string): Vorpal;
function description(description: string): Vorpal;
function banner(banner: string): Vorpal;
function delimiter(str: string): Vorpal;

Application Configuration

Command Management

Complete command registration and management system with support for arguments, options, validation, and advanced behaviors like modes and catch-all commands.

function command(name: string, desc?: string, opts?: object): Command;
function mode(name: string, desc?: string, opts?: object): Command;
function catch(name: string, desc?: string, opts?: object): Command;
function find(name: string): Command;

Command Management

Command Execution

Programmatic command execution with both synchronous and asynchronous support, plus argument parsing from process.argv.

function exec(cmd: string, args?: object, cb?: function): Promise|Vorpal;
function execSync(cmd: string, options?: object): any;
function parse(argv: array, options?: object): any;

Command Execution

User Interface Control

Terminal UI management including show/hide prompt, logging, and user interaction through prompts.

function show(): Vorpal;
function hide(): Vorpal;
function log(...args: any[]): Vorpal;
function prompt(options?: object, userCallback?: function): Promise;

User Interface

Extension System

Plugin architecture for importing command libraries and extending Vorpal functionality.

function use(commands: function|string|array|object, options?: object): Vorpal;

Extensions

History and Storage

Command history and local storage management for persistent data and user experience.

function history(id: string): Vorpal;
function historyStoragePath(path: string): Vorpal;
function localStorage(id: string): Vorpal;

History and Storage

Event Handling

Event system with hooks, pipes, and signal handling for advanced CLI behaviors.

function sigint(fn: function): Vorpal;
function pipe(fn: function): Vorpal;
function hook(fn?: function): Vorpal;
function help(fn: function): undefined;
function exit(options: object): undefined;

Event Handling

Session Management

Access and manage session instances and remote connections.

function getSessionById(id: string | number): Session;

Built-in Commands

Vorpal provides several built-in commands that are automatically available in every CLI application.

Help Command

Shows help information for all commands or a specific command.

// Built-in command: help [command...]
// Usage: help or help <command>
// Description: Output usage information

Usage Examples:

// Show all available commands
help

// Show help for specific command
help mycommand

// Show help for multiple commands  
help command1 command2

Exit Command

Exits the CLI application.

// Built-in commands: exit, quit
// Usage: exit or quit
// Description: Exit the application

Usage Examples:

// Exit the application
exit

// Alternative exit command
quit

Types

class Vorpal extends EventEmitter {
  constructor(): Vorpal;
  
  // Public properties
  commands: Command[];
  ui: UIObject;
  chalk: ChalkObject;
  lodash: LodashObject;
  util: VorpalUtilObject;
  Session: SessionConstructor;
  session: SessionInstance;
  server: ServerObject;
  cmdHistory: HistoryInstance;
  CmdHistoryExtension: HistoryConstructor;
  isCommandArgKeyPairNormalized: boolean;
  activeCommand: CommandInstance; // getter
}

interface ServerObject {
  sessions: SessionInstance[];
}

class Command {
  constructor(name: string, desc?: string, opts?: object): Command;
  
  // Configuration methods
  description(str?: string): string | Command;
  alias(...aliases: string[]): Command;
  option(flags: string, description: string, autocomplete?: any): Command;
  usage(str?: string): string | Command;
  arguments(desc: string): Command;
  hidden(): Command;
  allowUnknownOptions(allow?: boolean): Command;
  
  // Behavior methods
  action(fn: (args: any, callback: function) => void): Command;
  validate(fn: (args: any) => boolean | string): Command;
  cancel(fn: () => void): Command;
  autocomplete(obj: any): Command;
  types(types: any): Command;
  
  // Advanced methods
  parse(fn: (command: string, args: any) => string): Command;
  after(fn: () => void): Command;
  done(fn: () => void): Command;
  use(fn: (command: Command) => any): any;
  
  // Mode-specific methods
  init(fn: (args: any, callback: function) => void): Command;
  delimiter(delimiter: string): Command;
  
  // Help and information
  help(fn?: (cmd: Command) => string): Command;
  helpInformation(): string;
  optionHelp(): string;
  
  // Utility methods
  remove(): Command;
}

interface UIObject {
  // Output methods
  log(...args: any[]): UI;
  
  // Prompt methods  
  prompt(options: any, cb?: function): any;
  cancel(): UI;
  pause(): string | false;
  resume(val?: string): UI;
  
  // Redraw methods
  redraw(str: string): UI;
  'redraw.clear'(): UI;
  'redraw.done'(): UI;
}

interface HistoryInstance {
  setId(id: string): void;
  setStoragePath(path: string): void;
  getPreviousHistory(): string;
  getNextHistory(): string;
  peek(depth?: number): string;
  newCommand(cmd: string): void;
  enterMode(): void;
  exitMode(): void;
  clear(): void;
}

interface SessionInstance {
  delimiter(str?: string): string | Session;
  prompt(options: any, cb?: function): any;
  log(...args: any[]): void;
}

interface VorpalUtilObject {
  pad(str: string, width: number, padStr?: string): string;
  normalize(str: string): string;
  parseArgs(str: string): any;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/vorpal@1.12.x
Publish Source
CLI
Badge
tessl/npm-vorpal badge