0
# Command Management
1

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

4
## Capabilities
5

6
### Command Registration
7

8
Registers a new command in the Vorpal API with optional description and configuration options.
9

10
```javascript { .api }
11
/**
12
 * Registers a new command in the vorpal API
13
 * @param name - Command name with optional arguments <required> or [optional]
14
 * @param desc - Optional command description
15
 * @param opts - Optional options object with noHelp, mode, catch properties
16
 * @returns Command instance for further configuration
17
 */
18
function command(name: string, desc?: string, opts?: CommandOptions): Command;
19

20
interface CommandOptions {
21
  noHelp?: boolean;
22
  mode?: boolean;
23
  catch?: boolean;
24
}
25
```
26

27
**Usage Examples:**
28

29
```javascript
30
const vorpal = require('vorpal')();
31

32
// Simple command
33
vorpal
34
  .command('hello', 'Says hello')
35
  .action(function(args, callback) {
36
    this.log('Hello World!');
37
    callback();
38
  });
39

40
// Command with required argument
41
vorpal
42
  .command('greet <name>', 'Greets a person')
43
  .action(function(args, callback) {
44
    this.log(`Hello, ${args.name}!`);
45
    callback();
46
  });
47

48
// Command with optional argument
49
vorpal
50
  .command('say [message]', 'Says a message')
51
  .action(function(args, callback) {
52
    this.log(args.message || 'Nothing to say');
53
    callback();
54
  });
55
```
56

57
### Mode Command Registration
58

59
Registers a new 'mode' command that creates an interactive mode with its own command set.
60

61
```javascript { .api }
62
/**
63
 * Registers a new 'mode' command (interactive mode)
64
 * @param name - Mode command name
65
 * @param desc - Optional mode description
66
 * @param opts - Optional mode options
67
 * @returns Command instance for mode configuration
68
 */
69
function mode(name: string, desc?: string, opts?: object): Command;
70
```
71

72
**Usage Example:**
73

74
```javascript
75
const vorpal = require('vorpal')();
76

77
vorpal
78
  .mode('config', 'Enters configuration mode')
79
  .delimiter('config:')
80
  .init(function(args, callback) {
81
    this.log('Entering configuration mode...');
82
    callback();
83
  })
84
  .action(function(command, callback) {
85
    // Handle commands within this mode
86
    if (command === 'set param value') {
87
      this.log('Parameter set!');
88
    }
89
    callback();
90
  });
91
```
92

93
### Catch-All Command Registration
94

95
Registers a 'catch' command executed when no command matches are found.
96

97
```javascript { .api }
98
/**
99
 * Registers a 'catch' command executed when no command matches
100
 * @param name - Catch command pattern
101
 * @param desc - Optional catch description
102
 * @param opts - Optional catch options
103
 * @returns Command instance for catch configuration
104
 */
105
function catch(name: string, desc?: string, opts?: object): Command;
106
```
107

108
**Usage Example:**
109

110
```javascript
111
const vorpal = require('vorpal')();
112

113
vorpal
114
  .catch('[words...]', 'Handles unmatched commands')
115
  .action(function(args, callback) {
116
    this.log(`Command not found: ${args.words.join(' ')}`);
117
    this.log('Type "help" for available commands');
118
    callback();
119
  });
120
```
121

122
### Default Command Registration
123

124
Alias to the catch command for registering default handlers.
125

126
```javascript { .api }
127
/**
128
 * Alias to the catch command
129
 * @param name - Default command pattern
130
 * @param desc - Optional default description
131
 * @param opts - Optional default options
132
 * @returns Command instance for default configuration
133
 */
134
function default(name: string, desc?: string, opts?: object): Command;
135
```
136

137
### Command Lookup
138

139
Returns the instance of a given command by name.
140

141
```javascript { .api }
142
/**
143
 * Returns the instance of given command
144
 * @param name - Command name to find
145
 * @returns Command instance or undefined if not found
146
 */
147
function find(name: string): Command | undefined;
148
```
149

150
**Usage Example:**
151

152
```javascript
153
const vorpal = require('vorpal')();
154

155
vorpal.command('test', 'Test command');
156

157
const testCommand = vorpal.find('test');
158
if (testCommand) {
159
  // Modify the existing command
160
  testCommand.description('Updated test command');
161
}
162
```
163

164
## Command Configuration
165

166
### Command Description
167

168
Sets or gets the description for a command.
169

170
```javascript { .api }
171
/**
172
 * Defines description for given command
173
 * @param str - Description string (optional for getter)
174
 * @returns Description string (getter) or Command instance (setter)
175
 */
176
function description(str?: string): string | Command;
177
```
178

179
### Command Options
180

181
Registers an option for the command.
182

183
```javascript { .api }
184
/**
185
 * Registers an option for given command
186
 * @param flags - Option flags (e.g., '-v, --verbose')
187
 * @param description - Option description
188
 * @param autocomplete - Optional autocomplete configuration
189
 * @returns Command instance for chaining
190
 */
191
function option(flags: string, description: string, autocomplete?: any): Command;
192
```
193

194
**Usage Example:**
195

196
```javascript
197
vorpal
198
  .command('deploy <environment>')
199
  .option('-f, --force', 'Force deployment without confirmation')
200
  .option('-v, --verbose', 'Show detailed deployment logs')
201
  .action(function(args, callback) {
202
    if (args.options.force) {
203
      this.log('Forcing deployment...');
204
    }
205
    if (args.options.verbose) {
206
      this.log('Verbose mode enabled');
207
    }
208
    callback();
209
  });
210
```
211

212
### Command Aliases
213

214
Defines aliases for a command.
215

216
```javascript { .api }
217
/**
218
 * Defines an alias for a given command
219
 * @param aliases - Single alias string or array of aliases
220
 * @returns Command instance for chaining
221
 */
222
function alias(...aliases: string[] | string[][]): Command;
223
```
224

225
**Usage Example:**
226

227
```javascript
228
vorpal
229
  .command('list', 'Lists items')
230
  .alias('ls', 'dir')
231
  .action(function(args, callback) {
232
    this.log('Listing items...');
233
    callback();
234
  });
235
```
236

237
### Command Arguments
238

239
Sets the arguments description for a command.
240

241
```javascript { .api }
242
/**
243
 * Returns the commands arguments as string
244
 * @param desc - Arguments description
245
 * @returns Command instance for chaining
246
 */
247
function arguments(desc: string): Command;
248
```
249

250
### Command Usage
251

252
Sets or gets the usage string for help display.
253

254
```javascript { .api }
255
/**
256
 * Returns the command usage string for help
257
 * @param str - Usage string (optional for getter)
258
 * @returns Usage string (getter) or Command instance (setter)
259
 */
260
function usage(str?: string): string | Command;
261
```
262

263
## Command Behavior
264

265
### Command Action
266

267
Defines the action function to execute when the command is called.
268

269
```javascript { .api }
270
/**
271
 * Defines an action for a given command
272
 * @param fn - Action function receiving args and callback
273
 * @returns Command instance for chaining
274
 */
275
function action(fn: (args: CommandArgs, callback: function) => void): Command;
276

277
interface CommandArgs {
278
  [key: string]: any;
279
  options: { [key: string]: any };
280
}
281
```
282

283
### Command Validation
284

285
Defines a function to validate arguments before action is performed.
286

287
```javascript { .api }
288
/**
289
 * Defines a function to validate arguments before action
290
 * @param fn - Validation function returning true/false or error message
291
 * @returns Command instance for chaining
292
 */
293
function validate(fn: (args: CommandArgs) => boolean | string): Command;
294
```
295

296
### Command Cancellation
297

298
Defines a function to be called when the command is canceled.
299

300
```javascript { .api }
301
/**
302
 * Defines a function to be called when command is canceled
303
 * @param fn - Cancellation handler function
304
 * @returns Command instance for chaining
305
 */
306
function cancel(fn: () => void): Command;
307
```
308

309
### Command Completion
310

311
Defines a method to be called when the command set has completed.
312

313
```javascript { .api }
314
/**
315
 * Defines a method to be called when command set has completed
316
 * @param fn - Completion handler function
317
 * @returns Command instance for chaining
318
 */
319
function done(fn: () => void): Command;
320
```
321

322
### Post-Command Handler
323

324
Adds a command to be executed after command completion.
325

326
```javascript { .api }
327
/**
328
 * Adds a command to be executed after command completion
329
 * @param fn - Post-command handler function
330
 * @returns Command instance for chaining
331
 */
332
function after(fn: () => void): Command;
333
```
334

335
### Command Parser
336

337
Edits the raw command string before it is executed.
338

339
```javascript { .api }
340
/**
341
 * Edits the raw command string before execution
342
 * @param fn - Parser function that modifies command string
343
 * @returns Command instance for chaining
344
 */
345
function parse(fn: (command: string, args: CommandArgs) => string): Command;
346
```
347

348
## Mode-Specific Methods
349

350
### Mode Initialization
351

352
Defines an init action for a mode command.
353

354
```javascript { .api }
355
/**
356
 * Defines an init action for a mode command
357
 * @param fn - Initialization function for mode entry
358
 * @returns Command instance for chaining
359
 */
360
function init(fn: (args: CommandArgs, callback: function) => void): Command;
361
```
362

363
### Mode Delimiter
364

365
Defines a prompt delimiter for a mode once entered.
366

367
```javascript { .api }
368
/**
369
 * Defines a prompt delimiter for a mode once entered
370
 * @param delimiter - Delimiter string for mode prompt
371
 * @returns Command instance for chaining
372
 */
373
function delimiter(delimiter: string): Command;
374
```
375

376
## Autocomplete
377

378
### Autocomplete Configuration
379

380
Defines tabbed auto-completion for the given command.
381

382
```javascript { .api }
383
/**
384
 * Defines tabbed auto-completion for the given command
385
 * @param obj - Autocomplete configuration object
386
 * @returns Command instance for chaining
387
 */
388
function autocomplete(obj: AutocompleteConfig): Command;
389

390
interface AutocompleteConfig {
391
  [key: string]: string[] | function;
392
}
393
```
394

395
**Usage Example:**
396

397
```javascript
398
vorpal
399
  .command('connect <server>')
400
  .autocomplete({
401
    server: ['production', 'staging', 'development', 'local']
402
  })
403
  .action(function(args, callback) {
404
    this.log(`Connecting to ${args.server}...`);
405
    callback();
406
  });
407
```
408

409
## Advanced Configuration
410

411
### Static Typing
412

413
Sets arguments for static typing of options using minimist.
414

415
```javascript { .api }
416
/**
417
 * Sets args for static typing of options using minimist
418
 * @param types - Type configuration object
419
 * @returns Command instance for chaining
420
 */
421
function types(types: TypesConfig): Command;
422

423
interface TypesConfig {
424
  string?: string[];
425
  boolean?: string[];
426
  number?: string[];
427
}
428
```
429

430
### Hidden Commands
431

432
Hides command from the help menu.
433

434
```javascript { .api }
435
/**
436
 * Doesn't show command in the help menu
437
 * @returns Command instance for chaining
438
 */
439
function hidden(): Command;
440
```
441

442
### Unknown Options
443

444
Allows undeclared options to be passed in with the command.
445

446
```javascript { .api }
447
/**
448
 * Allows undeclared options to be passed in with the command
449
 * @param allow - Whether to allow unknown options (default true)
450
 * @returns Command instance for chaining
451
 */
452
function allowUnknownOptions(allow?: boolean): Command;
453
```
454

455
### Custom Help
456

457
Adds a custom handling for the --help flag.
458

459
```javascript { .api }
460
/**
461
 * Adds a custom handling for the --help flag
462
 * @param fn - Custom help function (optional)
463
 * @returns Command instance for chaining
464
 */
465
function help(fn?: (cmd: Command) => string): Command;
466
```
467

468
### Command Extensions
469

470
Allows composing other functions to extend the command.
471

472
```javascript { .api }
473
/**
474
 * Let's you compose other functions to extend the command
475
 * @param fn - Extension function
476
 * @returns Result of extension function
477
 */
478
function use(fn: (command: Command) => any): any;
479
```
480

481
### Command Removal
482

483
Removes command from parent Vorpal instance.
484

485
```javascript { .api }
486
/**
487
 * Removes self from Vorpal instance
488
 * @returns Command instance
489
 */
490
function remove(): Command;
491
```
492

493
## Help and Information
494

495
### Help Information
496

497
Returns the help info for given command.
498

499
```javascript { .api }
500
/**
501
 * Returns the help info for given command
502
 * @returns Help information string
503
 */
504
function helpInformation(): string;
505
```
506

507
### Option Help
508

509
Returns the help string for the command's options.
510

511
```javascript { .api }
512
/**
513
 * Returns the help string for the command's options
514
 * @returns Options help string
515
 */
516
function optionHelp(): string;
517
```
518

519
## Complete Command Example
520

521
```javascript
522
const vorpal = require('vorpal')();
523

524
vorpal
525
  .command('deploy <environment> [version]', 'Deploy application to environment')
526
  .alias('d')
527
  .option('-f, --force', 'Force deployment without confirmation')
528
  .option('-v, --verbose', 'Show detailed deployment logs')
529
  .option('-t, --timeout <seconds>', 'Deployment timeout in seconds')
530
  .types({
531
    string: ['environment', 'version'],
532
    number: ['timeout'],
533
    boolean: ['force', 'verbose']
534
  })
535
  .autocomplete({
536
    environment: ['production', 'staging', 'development']
537
  })
538
  .validate(function(args) {
539
    if (!['production', 'staging', 'development'].includes(args.environment)) {
540
      return 'Environment must be production, staging, or development';
541
    }
542
    return true;
543
  })
544
  .action(function(args, callback) {
545
    const env = args.environment;
546
    const version = args.version || 'latest';
547
    const force = args.options.force;
548
    const verbose = args.options.verbose;
549
    const timeout = args.options.timeout || 300;
550
    
551
    if (verbose) {
552
      this.log(`Deploying version ${version} to ${env}...`);
553
      this.log(`Timeout: ${timeout} seconds`);
554
      this.log(`Force mode: ${force ? 'enabled' : 'disabled'}`);
555
    }
556
    
557
    // Deploy logic here
558
    this.log(`Successfully deployed to ${env}!`);
559
    callback();
560
  });
561
```