0
# Help and Output
1

2
Configure help system, version information, usage messages, and output formatting.
3

4
## Capabilities
5

6
### Help Configuration
7

8
Configure help option and display behavior.
9

10
```javascript { .api }
11
/**
12
 * Configure help option
13
 * @param opt - Help option name or false to disable
14
 * @param msg - Help option description
15
 * @returns YargsInstance for chaining
16
 */
17
help(opt?: string | false, msg?: string): YargsInstance;
18

19
/**
20
 * Alias for help()
21
 */
22
addHelpOpt(opt?: string | false, msg?: string): YargsInstance;
23

24
/**
25
 * Display help text
26
 * @param level - Output level ('error', 'log') or custom function
27
 * @returns YargsInstance for chaining
28
 */
29
showHelp(level?: 'error' | 'log' | ((message: string) => void)): YargsInstance;
30

31
/**
32
 * Get help text as a Promise
33
 * @returns Promise resolving to help text string
34
 */
35
getHelp(): Promise<string>;
36
```
37

38
**Usage Examples:**
39

40
```javascript
41
// Default help option (--help, -h)
42
yargs()
43
  .option('port', { describe: 'Server port' })
44
  .help()
45
  .parse();
46

47
// Custom help option
48
yargs()
49
  .option('verbose', { describe: 'Verbose output' })
50
  .help('info', 'Show application info')
51
  .parse();
52

53
// Disable help
54
yargs()
55
  .option('quiet', { describe: 'Quiet mode' })
56
  .help(false)
57
  .parse();
58

59
// Show help programmatically
60
const yarg = yargs()
61
  .option('port', { describe: 'Server port' });
62

63
yarg.showHelp(); // Outputs to console
64
yarg.showHelp('error'); // Outputs to stderr
65
yarg.showHelp(console.error); // Custom output function
66

67
// Get help as string
68
yarg.getHelp().then(helpText => {
69
  console.log('Help text:', helpText);
70
});
71
```
72

73
### Version Configuration
74

75
Configure version option and display.
76

77
```javascript { .api }
78
/**
79
 * Configure version option
80
 * @param opt - Version option name or false to disable
81
 * @param msg - Version option description
82
 * @param ver - Version string
83
 * @returns YargsInstance for chaining
84
 */
85
version(opt?: string | false, msg?: string, ver?: string): YargsInstance;
86

87
/**
88
 * Display version information
89
 * @param level - Output level ('error', 'log') or custom function
90
 * @returns YargsInstance for chaining
91
 */
92
showVersion(level?: 'error' | 'log' | ((message: string) => void)): YargsInstance;
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
// Auto-detect version from package.json
99
yargs()
100
  .version()
101
  .parse();
102

103
// Custom version string
104
yargs()
105
  .version('1.2.3')
106
  .parse();
107

108
// Custom version option and message
109
yargs()
110
  .version('ver', 'Show application version', '2.0.0')
111
  .parse();
112

113
// Disable version
114
yargs()
115
  .version(false)
116
  .parse();
117

118
// Show version programmatically
119
yargs()
120
  .version('1.0.0')
121
  .showVersion(); // Outputs version
122
```
123

124
### Usage Messages
125

126
Set usage messages and examples.
127

128
```javascript { .api }
129
/**
130
 * Set usage message or define default command
131
 * @param msg - Usage message template
132
 * @param description - Command description (if defining command)
133
 * @param builder - Command builder
134
 * @param handler - Command handler
135
 * @returns YargsInstance for chaining
136
 */
137
usage(msg: string | null, description?: string | boolean, builder?: CommandBuilderDefinition | CommandBuilder, handler?: CommandHandlerCallback): YargsInstance;
138

139
/**
140
 * Add usage examples
141
 * @param cmd - Example command or array of [command, description] pairs
142
 * @param description - Example description
143
 * @returns YargsInstance for chaining
144
 */
145
example(cmd: string | [string, string?][], description?: string): YargsInstance;
146

147
/**
148
 * Set epilogue text (shown after help)
149
 * @param msg - Epilogue message
150
 * @returns YargsInstance for chaining
151
 */
152
epilogue(msg: string): YargsInstance;
153

154
/**
155
 * Alias for epilogue()
156
 */
157
epilog(msg: string): YargsInstance;
158
```
159

160
**Usage Examples:**
161

162
```javascript
163
// Custom usage message
164
yargs()
165
  .usage('Usage: $0 [options]')
166
  .option('port', { describe: 'Server port' })
167
  .parse();
168

169
// Usage with placeholders
170
yargs()
171
  .usage('Usage: $0 <command> [options]')
172
  .command('start', 'Start the service')
173
  .parse();
174

175
// Single example
176
yargs()
177
  .example('$0 --port 3000', 'Start server on port 3000')
178
  .parse();
179

180
// Multiple examples
181
yargs()
182
  .example([
183
    ['$0 start --port 3000', 'Start server on port 3000'],
184
    ['$0 stop', 'Stop the server'],
185
    ['$0 restart --timeout 30', 'Restart with 30s timeout']
186
  ])
187
  .parse();
188

189
// Epilogue
190
yargs()
191
  .option('verbose', { describe: 'Verbose output' })
192
  .epilogue('For more information, visit https://example.com/docs')
193
  .parse();
194

195
// Usage as default command
196
yargs()
197
  .usage('$0 [name]', 'Greet someone', (yargs) => {
198
    return yargs.positional('name', {
199
      describe: 'Name to greet',
200
      default: 'World'
201
    });
202
  }, (argv) => {
203
    console.log(`Hello, ${argv.name}!`);
204
  })
205
  .parse();
206
```
207

208
### Hidden Options
209

210
Configure hidden options display.
211

212
```javascript { .api }
213
/**
214
 * Configure show-hidden option
215
 * @param opt - Show-hidden option name or false to disable
216
 * @param msg - Show-hidden option description
217
 * @returns YargsInstance for chaining
218
 */
219
showHidden(opt?: string | false, msg?: string): YargsInstance;
220

221
/**
222
 * Alias for showHidden()
223
 */
224
addShowHiddenOpt(opt?: string | false, msg?: string): YargsInstance;
225
```
226

227
**Usage Examples:**
228

229
```javascript
230
yargs()
231
  .option('verbose', { describe: 'Verbose output' })
232
  .option('debug', { describe: 'Debug mode', hidden: true })
233
  .showHidden() // Adds --show-hidden option
234
  .parse();
235

236
// Custom show-hidden option
237
yargs()
238
  .option('secret', { describe: 'Secret option', hidden: true })
239
  .showHidden('reveal', 'Show hidden options')
240
  .parse();
241
```
242

243
### Help on Failure
244

245
Configure help display when validation fails.
246

247
```javascript { .api }
248
/**
249
 * Show help when validation fails
250
 * @param enabled - Whether to show help on failure, or custom message
251
 * @param message - Custom failure message
252
 * @returns YargsInstance for chaining
253
 */
254
showHelpOnFail(enabled?: string | boolean, message?: string): YargsInstance;
255
```
256

257
**Usage Examples:**
258

259
```javascript
260
// Show help on any failure
261
yargs()
262
  .option('required', { demandOption: true })
263
  .showHelpOnFail(true)
264
  .parse();
265

266
// Custom failure message
267
yargs()
268
  .demandCommand(1)
269
  .showHelpOnFail(false, 'Specify a command to get started')
270
  .parse();
271

272
// Custom message with help
273
yargs()
274
  .option('config', { demandOption: true })
275
  .showHelpOnFail('Try --help for available options')
276
  .parse();
277
```
278

279
### Option Grouping
280

281
Group related options in help display.
282

283
```javascript { .api }
284
/**
285
 * Group options under headings in help
286
 * @param opts - Option name(s) to group
287
 * @param groupName - Group heading name
288
 * @returns YargsInstance for chaining
289
 */
290
group(opts: string | string[], groupName: string): YargsInstance;
291

292
/**
293
 * Get current option groups
294
 * @returns Object mapping group names to option arrays
295
 */
296
getGroups(): Dictionary<string[]>;
297
```
298

299
**Usage Examples:**
300

301
```javascript
302
yargs()
303
  .option('host', { describe: 'Server host' })
304
  .option('port', { describe: 'Server port' })
305
  .option('verbose', { describe: 'Verbose output' })
306
  .option('quiet', { describe: 'Quiet mode' })
307
  .group(['host', 'port'], 'Server Options:')
308
  .group(['verbose', 'quiet'], 'Output Options:')
309
  .parse();
310

311
// Get current groups
312
const groups = yargs().getGroups();
313
console.log('Option groups:', groups);
314
```
315

316
### Failure Handling
317

318
Configure custom failure handling.
319

320
```javascript { .api }
321
/**
322
 * Set custom failure handler
323
 * @param f - Failure handler function or false to disable
324
 * @returns YargsInstance for chaining
325
 */
326
fail(f: ((message: string, error: Error, yargs: YargsInstance) => void) | boolean): YargsInstance;
327
```
328

329
**Usage Examples:**
330

331
```javascript
332
// Custom failure handler
333
yargs()
334
  .option('config', { demandOption: true })
335
  .fail((msg, err, yargs) => {
336
    console.error('Configuration Error:', msg);
337
    console.error('Use --help for usage information');
338
    process.exit(1);
339
  })
340
  .parse();
341

342
// Disable default failure handling
343
yargs()
344
  .demandCommand(1)
345
  .fail(false)
346
  .parse();
347
```
348

349
### Locale and Internationalization
350

351
Configure localization and custom strings.
352

353
```javascript { .api }
354
/**
355
 * Set or get current locale
356
 * @param locale - Locale string (e.g., 'en', 'es', 'fr')
357
 * @returns YargsInstance for chaining or current locale
358
 */
359
locale(locale?: string): YargsInstance | string;
360

361
/**
362
 * Control automatic locale detection
363
 * @param detect - Whether to detect locale from environment
364
 * @returns YargsInstance for chaining
365
 */
366
detectLocale(detect: boolean): YargsInstance;
367

368
/**
369
 * Update locale strings
370
 * @param obj - Object mapping string keys to translated values
371
 * @returns YargsInstance for chaining
372
 */
373
updateStrings(obj: Dictionary<string>): YargsInstance;
374

375
/**
376
 * Alias for updateStrings()
377
 */
378
updateLocale(obj: Dictionary<string>): YargsInstance;
379

380
/**
381
 * Get current locale detection setting
382
 * @returns Whether locale detection is enabled
383
 */
384
getDetectLocale(): boolean;
385
```
386

387
**Usage Examples:**
388

389
```javascript
390
// Set locale
391
yargs()
392
  .locale('es')
393
  .help()
394
  .parse();
395

396
// Get current locale
397
const currentLocale = yargs().locale();
398
console.log('Current locale:', currentLocale);
399

400
// Disable auto-detection
401
yargs()
402
  .detectLocale(false)
403
  .locale('en')
404
  .parse();
405

406
// Custom strings
407
yargs()
408
  .updateStrings({
409
    'Commands:': 'Comandos:',
410
    'Options:': 'Opciones:',
411
    'Show help': 'Mostrar ayuda'
412
  })
413
  .help()
414
  .parse();
415
```
416

417
## Types
418

419
```javascript { .api }
420
/**
421
 * Help display level options
422
 */
423
type HelpLevel = 'error' | 'log' | ((message: string) => void);
424

425
/**
426
 * Failure handler function
427
 */
428
type FailureFunction = (message: string, error: Error, yargs: YargsInstance) => void;
429

430
/**
431
 * Dictionary type for string mappings
432
 */
433
type Dictionary<T = any> = { [key: string]: T };
434

435
/**
436
 * Usage configuration options
437
 */
438
interface UsageConfiguration {
439
  /** Should types be hidden when usage is displayed */
440
  'hide-types'?: boolean;
441
}
442
```