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