or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

commands.mdconfiguration.mdevents.mdexecution.mdextensions.mdindex.mdstorage.mdui.md
tile.json

tessl/npm-vorpal

Node's first framework for building immersive CLI apps.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/vorpal@1.12.x

To install, run

npx @tessl/cli install tessl/npm-vorpal@1.12.0

index.mddocs/

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;
}