0
# Vorpal
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: vorpal
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES6 with Babel)
9
- **Installation**: `npm install vorpal`
10
11
## Core Imports
12
13
```javascript
14
const Vorpal = require('vorpal');
15
```
16
17
For ES6/TypeScript environments:
18
19
```javascript
20
import Vorpal from 'vorpal';
21
```
22
23
## Basic Usage
24
25
```javascript
26
const vorpal = require('vorpal')();
27
28
// Create a command
29
vorpal
30
.command('hello [name]', 'Outputs a greeting')
31
.action(function(args, callback) {
32
this.log(`Hello, ${args.name || 'World'}!`);
33
callback();
34
});
35
36
// Start the interactive CLI
37
vorpal
38
.delimiter('myapp$')
39
.show();
40
```
41
42
## Architecture
43
44
Vorpal is built around several key components:
45
46
- **Vorpal Instance**: Main application controller managing commands, sessions, and UI
47
- **Command System**: Registration, parsing, validation, and execution of CLI commands
48
- **Session Management**: User session handling with local and remote support
49
- **UI Layer**: Terminal interface with prompt rendering, history, and autocomplete
50
- **Extension System**: Plugin architecture for extending functionality with modules
51
- **Event System**: Rich event emission for hooks, intercepts, and custom behaviors
52
53
## Capabilities
54
55
### Application Configuration
56
57
Core configuration methods for setting up your CLI application including version, title, description, and prompt delimiter.
58
59
```javascript { .api }
60
function version(version: string): Vorpal;
61
function title(title: string): Vorpal;
62
function description(description: string): Vorpal;
63
function banner(banner: string): Vorpal;
64
function delimiter(str: string): Vorpal;
65
```
66
67
[Application Configuration](./configuration.md)
68
69
### Command Management
70
71
Complete command registration and management system with support for arguments, options, validation, and advanced behaviors like modes and catch-all commands.
72
73
```javascript { .api }
74
function command(name: string, desc?: string, opts?: object): Command;
75
function mode(name: string, desc?: string, opts?: object): Command;
76
function catch(name: string, desc?: string, opts?: object): Command;
77
function find(name: string): Command;
78
```
79
80
[Command Management](./commands.md)
81
82
### Command Execution
83
84
Programmatic command execution with both synchronous and asynchronous support, plus argument parsing from process.argv.
85
86
```javascript { .api }
87
function exec(cmd: string, args?: object, cb?: function): Promise|Vorpal;
88
function execSync(cmd: string, options?: object): any;
89
function parse(argv: array, options?: object): any;
90
```
91
92
[Command Execution](./execution.md)
93
94
### User Interface Control
95
96
Terminal UI management including show/hide prompt, logging, and user interaction through prompts.
97
98
```javascript { .api }
99
function show(): Vorpal;
100
function hide(): Vorpal;
101
function log(...args: any[]): Vorpal;
102
function prompt(options?: object, userCallback?: function): Promise;
103
```
104
105
[User Interface](./ui.md)
106
107
### Extension System
108
109
Plugin architecture for importing command libraries and extending Vorpal functionality.
110
111
```javascript { .api }
112
function use(commands: function|string|array|object, options?: object): Vorpal;
113
```
114
115
[Extensions](./extensions.md)
116
117
### History and Storage
118
119
Command history and local storage management for persistent data and user experience.
120
121
```javascript { .api }
122
function history(id: string): Vorpal;
123
function historyStoragePath(path: string): Vorpal;
124
function localStorage(id: string): Vorpal;
125
```
126
127
[History and Storage](./storage.md)
128
129
### Event Handling
130
131
Event system with hooks, pipes, and signal handling for advanced CLI behaviors.
132
133
```javascript { .api }
134
function sigint(fn: function): Vorpal;
135
function pipe(fn: function): Vorpal;
136
function hook(fn?: function): Vorpal;
137
function help(fn: function): undefined;
138
function exit(options: object): undefined;
139
```
140
141
[Event Handling](./events.md)
142
143
### Session Management
144
145
Access and manage session instances and remote connections.
146
147
```javascript { .api }
148
function getSessionById(id: string | number): Session;
149
```
150
151
## Built-in Commands
152
153
Vorpal provides several built-in commands that are automatically available in every CLI application.
154
155
### Help Command
156
157
Shows help information for all commands or a specific command.
158
159
```javascript { .api }
160
// Built-in command: help [command...]
161
// Usage: help or help <command>
162
// Description: Output usage information
163
```
164
165
**Usage Examples:**
166
167
```javascript
168
// Show all available commands
169
help
170
171
// Show help for specific command
172
help mycommand
173
174
// Show help for multiple commands
175
help command1 command2
176
```
177
178
### Exit Command
179
180
Exits the CLI application.
181
182
```javascript { .api }
183
// Built-in commands: exit, quit
184
// Usage: exit or quit
185
// Description: Exit the application
186
```
187
188
**Usage Examples:**
189
190
```javascript
191
// Exit the application
192
exit
193
194
// Alternative exit command
195
quit
196
```
197
198
## Types
199
200
```javascript { .api }
201
class Vorpal extends EventEmitter {
202
constructor(): Vorpal;
203
204
// Public properties
205
commands: Command[];
206
ui: UIObject;
207
chalk: ChalkObject;
208
lodash: LodashObject;
209
util: VorpalUtilObject;
210
Session: SessionConstructor;
211
session: SessionInstance;
212
server: ServerObject;
213
cmdHistory: HistoryInstance;
214
CmdHistoryExtension: HistoryConstructor;
215
isCommandArgKeyPairNormalized: boolean;
216
activeCommand: CommandInstance; // getter
217
}
218
219
interface ServerObject {
220
sessions: SessionInstance[];
221
}
222
223
class Command {
224
constructor(name: string, desc?: string, opts?: object): Command;
225
226
// Configuration methods
227
description(str?: string): string | Command;
228
alias(...aliases: string[]): Command;
229
option(flags: string, description: string, autocomplete?: any): Command;
230
usage(str?: string): string | Command;
231
arguments(desc: string): Command;
232
hidden(): Command;
233
allowUnknownOptions(allow?: boolean): Command;
234
235
// Behavior methods
236
action(fn: (args: any, callback: function) => void): Command;
237
validate(fn: (args: any) => boolean | string): Command;
238
cancel(fn: () => void): Command;
239
autocomplete(obj: any): Command;
240
types(types: any): Command;
241
242
// Advanced methods
243
parse(fn: (command: string, args: any) => string): Command;
244
after(fn: () => void): Command;
245
done(fn: () => void): Command;
246
use(fn: (command: Command) => any): any;
247
248
// Mode-specific methods
249
init(fn: (args: any, callback: function) => void): Command;
250
delimiter(delimiter: string): Command;
251
252
// Help and information
253
help(fn?: (cmd: Command) => string): Command;
254
helpInformation(): string;
255
optionHelp(): string;
256
257
// Utility methods
258
remove(): Command;
259
}
260
261
interface UIObject {
262
// Output methods
263
log(...args: any[]): UI;
264
265
// Prompt methods
266
prompt(options: any, cb?: function): any;
267
cancel(): UI;
268
pause(): string | false;
269
resume(val?: string): UI;
270
271
// Redraw methods
272
redraw(str: string): UI;
273
'redraw.clear'(): UI;
274
'redraw.done'(): UI;
275
}
276
277
interface HistoryInstance {
278
setId(id: string): void;
279
setStoragePath(path: string): void;
280
getPreviousHistory(): string;
281
getNextHistory(): string;
282
peek(depth?: number): string;
283
newCommand(cmd: string): void;
284
enterMode(): void;
285
exitMode(): void;
286
clear(): void;
287
}
288
289
interface SessionInstance {
290
delimiter(str?: string): string | Session;
291
prompt(options: any, cb?: function): any;
292
log(...args: any[]): void;
293
}
294
295
interface VorpalUtilObject {
296
pad(str: string, width: number, padStr?: string): string;
297
normalize(str: string): string;
298
parseArgs(str: string): any;
299
}
300
```