0
# Option Definition
1

2
Define and configure command-line options with types, validation, defaults, and relationships between options.
3

4
## Capabilities
5

6
### Basic Option Definition
7

8
Define options with comprehensive configuration.
9

10
```javascript { .api }
11
/**
12
 * Define a command-line option
13
 * @param key - Option name or configuration object
14
 * @param opt - Option configuration
15
 * @returns YargsInstance for chaining
16
 */
17
option(key: string | Dictionary<OptionDefinition>, opt?: OptionDefinition): YargsInstance;
18

19
/**
20
 * Alias for option()
21
 */
22
options(key: string | Dictionary<OptionDefinition>, opt?: OptionDefinition): YargsInstance;
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
// Single option
29
yargs()
30
  .option('port', {
31
    alias: 'p',
32
    type: 'number',
33
    default: 3000,
34
    description: 'Port to bind on'
35
  })
36
  .parse();
37

38
// Multiple options object
39
yargs()
40
  .options({
41
    port: {
42
      alias: 'p',
43
      type: 'number',
44
      default: 3000,
45
      description: 'Port to bind on'
46
    },
47
    verbose: {
48
      alias: 'v',
49
      type: 'boolean',
50
      description: 'Enable verbose logging'
51
    }
52
  })
53
  .parse();
54
```
55

56
### Option Aliases
57

58
Define alternative names for options.
59

60
```javascript { .api }
61
/**
62
 * Define option aliases
63
 * @param key - Option name, array of names, or alias map
64
 * @param value - Alias name(s) for the option
65
 * @returns YargsInstance for chaining
66
 */
67
alias(key: string | string[] | Dictionary<string | string[]>, value?: string | string[]): YargsInstance;
68
```
69

70
**Usage Examples:**
71

72
```javascript
73
// Single alias
74
yargs()
75
  .option('verbose')
76
  .alias('verbose', 'v')
77
  .parse();
78

79
// Multiple aliases
80
yargs()
81
  .option('output')
82
  .alias('output', ['o', 'out'])
83
  .parse();
84

85
// Alias object
86
yargs()
87
  .alias({
88
    verbose: 'v',
89
    output: ['o', 'out'],
90
    help: 'h'
91
  })
92
  .parse();
93
```
94

95
### Option Types
96

97
Specify option types for proper parsing and validation.
98

99
```javascript { .api }
100
/**
101
 * Mark options as arrays
102
 * @param keys - Option name(s) to treat as arrays
103
 * @returns YargsInstance for chaining
104
 */
105
array(keys: string | string[]): YargsInstance;
106

107
/**
108
 * Mark options as booleans
109
 * @param keys - Option name(s) to treat as booleans
110
 * @returns YargsInstance for chaining
111
 */
112
boolean(keys: string | string[]): YargsInstance;
113

114
/**
115
 * Mark options as numbers
116
 * @param keys - Option name(s) to treat as numbers
117
 * @returns YargsInstance for chaining
118
 */
119
number(keys: string | string[]): YargsInstance;
120

121
/**
122
 * Mark options as strings
123
 * @param keys - Option name(s) to treat as strings
124
 * @returns YargsInstance for chaining
125
 */
126
string(keys: string | string[]): YargsInstance;
127

128
/**
129
 * Mark options as counters (increment on each use)
130
 * @param keys - Option name(s) to treat as counters
131
 * @returns YargsInstance for chaining
132
 */
133
count(keys: string | string[]): YargsInstance;
134
```
135

136
**Usage Examples:**
137

138
```javascript
139
yargs()
140
  .option('files', { description: 'Input files' })
141
  .array('files')                    // --files a.txt b.txt c.txt
142
  .option('verbose', { description: 'Verbose output' })
143
  .boolean('verbose')                // --verbose or --no-verbose
144
  .option('port', { description: 'Port number' })
145
  .number('port')                    // --port 3000
146
  .option('name', { description: 'Project name' })
147
  .string('name')                    // --name "My Project"
148
  .option('debug', { description: 'Debug level' })
149
  .count('debug')                    // -d -d -d or -ddd
150
  .parse();
151
```
152

153
### Default Values
154

155
Set default values for options.
156

157
```javascript { .api }
158
/**
159
 * Set default values for options
160
 * @param key - Option name, array, or defaults object
161
 * @param value - Default value
162
 * @param defaultDescription - Description of default value
163
 * @returns YargsInstance for chaining
164
 */
165
default(key: string | string[] | Dictionary<any>, value?: any, defaultDescription?: string): YargsInstance;
166

167
/**
168
 * Alias for default()
169
 */
170
defaults(key: string | string[] | Dictionary<any>, value?: any, defaultDescription?: string): YargsInstance;
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
// Single default
177
yargs()
178
  .option('port')
179
  .default('port', 3000)
180
  .parse();
181

182
// Default with description
183
yargs()
184
  .option('config')
185
  .default('config', './config.json', 'default configuration file')
186
  .parse();
187

188
// Multiple defaults
189
yargs()
190
  .defaults({
191
    port: 3000,
192
    host: 'localhost',
193
    verbose: false
194
  })
195
  .parse();
196

197
// Function defaults (evaluated at parse time)
198
yargs()
199
  .default('timestamp', () => Date.now())
200
  .parse();
201
```
202

203
### Option Descriptions
204

205
Add descriptions for help text generation.
206

207
```javascript { .api }
208
/**
209
 * Add descriptions for options
210
 * @param keys - Option name, array, or description map
211
 * @param description - Description text
212
 * @returns YargsInstance for chaining
213
 */
214
describe(keys: string | string[] | Dictionary<string>, description?: string): YargsInstance;
215
```
216

217
**Usage Examples:**
218

219
```javascript
220
// Single description
221
yargs()
222
  .option('port')
223
  .describe('port', 'Port to bind the server on')
224
  .parse();
225

226
// Multiple descriptions
227
yargs()
228
  .describe({
229
    port: 'Port to bind the server on',
230
    verbose: 'Enable verbose logging',
231
    config: 'Path to configuration file'
232
  })
233
  .parse();
234
```
235

236
### Choice Restrictions
237

238
Restrict option values to specific choices.
239

240
```javascript { .api }
241
/**
242
 * Restrict option values to specific choices
243
 * @param key - Option name, array, or choices map
244
 * @param value - Array of valid choices
245
 * @returns YargsInstance for chaining
246
 */
247
choices(key: string | string[] | Dictionary<string | string[]>, value?: string | string[]): YargsInstance;
248
```
249

250
**Usage Examples:**
251

252
```javascript
253
// Single choice restriction
254
yargs()
255
  .option('env')
256
  .choices('env', ['development', 'staging', 'production'])
257
  .parse();
258

259
// Multiple choice restrictions
260
yargs()
261
  .choices({
262
    env: ['development', 'staging', 'production'],
263
    log: ['error', 'warn', 'info', 'debug']
264
  })
265
  .parse();
266
```
267

268
### Value Coercion
269

270
Transform option values during parsing.
271

272
```javascript { .api }
273
/**
274
 * Transform option values using coercion functions
275
 * @param keys - Option name(s) or coercion map
276
 * @param value - Coercion function
277
 * @returns YargsInstance for chaining
278
 */
279
coerce(keys: string | string[] | Dictionary<CoerceCallback>, value?: CoerceCallback): YargsInstance;
280
```
281

282
**Usage Examples:**
283

284
```javascript
285
// Single coercion
286
yargs()
287
  .option('date')
288
  .coerce('date', (arg) => new Date(arg))
289
  .parse();
290

291
// Multiple coercions
292
yargs()
293
  .coerce({
294
    port: (arg) => parseInt(arg, 10),
295
    tags: (arg) => Array.isArray(arg) ? arg : [arg],
296
    config: (arg) => JSON.parse(require('fs').readFileSync(arg, 'utf8'))
297
  })
298
  .parse();
299

300
// Array coercion
301
yargs()
302
  .option('files')
303
  .array('files')
304
  .coerce('files', (files) => files.map(f => path.resolve(f)))
305
  .parse();
306
```
307

308
### Advanced Option Configuration
309

310
Additional configuration options for fine-tuned behavior.
311

312
```javascript { .api }
313
/**
314
 * Specify number of arguments an option expects
315
 * @param key - Option name or nargs map
316
 * @param value - Number of arguments
317
 * @returns YargsInstance for chaining
318
 */
319
nargs(key: string | string[] | Dictionary<number>, value?: number): YargsInstance;
320

321
/**
322
 * Require options to have arguments
323
 * @param keys - Option name(s) that require arguments
324
 * @returns YargsInstance for chaining
325
 */
326
requiresArg(keys: string | string[] | Dictionary): YargsInstance;
327

328
/**
329
 * Normalize file paths
330
 * @param keys - Option name(s) to normalize as paths
331
 * @returns YargsInstance for chaining
332
 */
333
normalize(keys: string | string[]): YargsInstance;
334

335
/**
336
 * Hide options from help text
337
 * @param key - Option name to hide
338
 * @returns YargsInstance for chaining
339
 */
340
hide(key: string): YargsInstance;
341

342
/**
343
 * Skip validation for specific options
344
 * @param keys - Option name(s) to skip validation for
345
 * @returns YargsInstance for chaining
346
 */
347
skipValidation(keys: string | string[]): YargsInstance;
348
```
349

350
**Usage Examples:**
351

352
```javascript
353
yargs()
354
  .option('coords', { description: 'X and Y coordinates' })
355
  .nargs('coords', 2)               // --coords 10 20
356
  
357
  .option('output', { description: 'Output file' })
358
  .requiresArg('output')            // --output requires a value
359
  
360
  .option('input', { description: 'Input file path' })
361
  .normalize('input')               // Normalizes file paths
362
  
363
  .option('secret', { description: 'API secret' })
364
  .hide('secret')                   // Hidden from help
365
  
366
  .option('raw', { description: 'Skip validation' })
367
  .skipValidation('raw')            // Skip validation for this option
368
  .parse();
369
```
370

371
## Types
372

373
```javascript { .api }
374
/**
375
 * Option definition configuration
376
 */
377
interface OptionDefinition {
378
  alias?: string | string[];
379
  array?: boolean;
380
  boolean?: boolean;
381
  choices?: string | string[];
382
  coerce?: (arg: any) => any;
383
  config?: boolean;
384
  configParser?: (configPath: string) => object;
385
  conflicts?: string | string[];
386
  count?: boolean;
387
  default?: any;
388
  defaultDescription?: string;
389
  deprecate?: string | boolean;
390
  deprecated?: string | boolean;
391
  desc?: string;
392
  describe?: string;
393
  description?: string;
394
  demand?: string | true;
395
  demandOption?: string | true;
396
  global?: boolean;
397
  group?: string;
398
  hidden?: boolean;
399
  implies?: string | number | (string | number)[];
400
  nargs?: number;
401
  normalize?: boolean;
402
  number?: boolean;
403
  require?: string | true;
404
  required?: string | true;
405
  requiresArg?: boolean;
406
  skipValidation?: boolean;
407
  string?: boolean;
408
  type?: 'array' | 'boolean' | 'count' | 'number' | 'string';
409
}
410

411
/**
412
 * Coercion callback function
413
 */
414
type CoerceCallback = (arg: any) => any;
415

416
/**
417
 * Dictionary type for option maps
418
 */
419
type Dictionary<T = any> = { [key: string]: T };
420
```