0
# Configuration Options
1

2
yargs-parser provides extensive configuration options to control parsing behavior. These options can be set via the `configuration` property in parser options.
3

4
## Import
5

6
```typescript
7
import parser from "yargs-parser";
8
```
9

10
## API
11

12
```typescript { .api }
13
interface Configuration {
14
  /** Should variables prefixed with --no be treated as negations? Default is `true` */
15
  'boolean-negation': boolean;
16
  /** Should hyphenated arguments be expanded into camel-case aliases? Default is `true` */
17
  'camel-case-expansion': boolean;
18
  /** Should arrays be combined when provided by both command line arguments and a configuration file? Default is `false` */
19
  'combine-arrays': boolean;
20
  /** Should keys that contain `.` be treated as objects? Default is `true` */
21
  'dot-notation': boolean;
22
  /** Should arguments be coerced into an array when duplicated? Default is `true` */
23
  'duplicate-arguments-array': boolean;
24
  /** Should array arguments be coerced into a single array when duplicated? Default is `true` */
25
  'flatten-duplicate-arrays': boolean;
26
  /** Should arrays consume more than one positional argument following their flag? Default is `true` */
27
  'greedy-arrays': boolean;
28
  /** Should parsing stop at the first text argument? This is similar to how e.g. ssh parses its command line. Default is `false` */
29
  'halt-at-non-option': boolean;
30
  /** Should nargs consume dash options as well as positional arguments? Default is `false` */
31
  'nargs-eats-options': boolean;
32
  /** The prefix to use for negated boolean variables. Default is `'no-'` */
33
  'negation-prefix': string;
34
  /** Should positional values that look like numbers be parsed? Default is `true` */
35
  'parse-positional-numbers': boolean;
36
  /** Should keys that look like numbers be treated as such? Default is `true` */
37
  'parse-numbers': boolean;
38
  /** Should unparsed flags be stored in -- or _? Default is `false` */
39
  'populate--': boolean;
40
  /** Should a placeholder be added for keys not set via the corresponding CLI argument? Default is `false` */
41
  'set-placeholder-key': boolean;
42
  /** Should a group of short-options be treated as boolean flags? Default is `true` */
43
  'short-option-groups': boolean;
44
  /** Should aliases be removed before returning results? Default is `false` */
45
  'strip-aliased': boolean;
46
  /** Should dashed keys be removed before returning results? This option has no effect if camel-case-expansion is disabled. Default is `false` */
47
  'strip-dashed': boolean;
48
  /** Should unknown options be treated like regular arguments? An unknown option is one that is not configured in opts. Default is `false` */
49
  'unknown-options-as-args': boolean;
50
}
51
```
52

53
## Basic Usage
54

55
```typescript
56
const result = parser(['--foo-bar', 'value'], {
57
  configuration: {
58
    'camel-case-expansion': false,
59
    'dot-notation': true
60
  }
61
});
62
```
63

64
## Configuration Options Detail
65

66
### Boolean Negation
67

68
Control how `--no-` prefixed options are handled.
69

70
```typescript
71
// Default behavior (boolean-negation: true)
72
const withNegation = parser(['--no-debug']);
73
console.log(withNegation);
74
// Output: { _: [], debug: false }
75

76
// Disabled boolean negation
77
const withoutNegation = parser(['--no-debug'], {
78
  configuration: { 'boolean-negation': false }
79
});
80
console.log(withoutNegation);
81
// Output: { _: [], 'no-debug': true }
82
```
83

84
### Camel Case Expansion
85

86
Control automatic camelCase alias creation for hyphenated options.
87

88
```typescript
89
// Default behavior (camel-case-expansion: true)
90
const withCamelCase = parser(['--foo-bar', 'value']);
91
console.log(withCamelCase);
92
// Output: { _: [], 'foo-bar': 'value', fooBar: 'value' }
93

94
// Disabled camel case expansion
95
const withoutCamelCase = parser(['--foo-bar', 'value'], {
96
  configuration: { 'camel-case-expansion': false }
97
});
98
console.log(withoutCamelCase);
99
// Output: { _: [], 'foo-bar': 'value' }
100
```
101

102
### Dot Notation
103

104
Control parsing of dotted keys as nested objects.
105

106
```typescript
107
// Default behavior (dot-notation: true)
108
const withDotNotation = parser(['--db.host', 'localhost', '--db.port', '5432']);
109
console.log(withDotNotation);
110
// Output: { _: [], db: { host: 'localhost', port: 5432 } }
111

112
// Disabled dot notation
113
const withoutDotNotation = parser(['--db.host', 'localhost'], {
114
  configuration: { 'dot-notation': false }
115
});
116
console.log(withoutDotNotation);
117
// Output: { _: [], 'db.host': 'localhost' }
118
```
119

120
### Parse Numbers
121

122
Control automatic number parsing for option values.
123

124
```typescript
125
// Default behavior (parse-numbers: true)
126
const withNumberParsing = parser(['--port', '3000', '--ratio', '0.75']);
127
console.log(withNumberParsing);
128
// Output: { _: [], port: 3000, ratio: 0.75 }
129

130
// Disabled number parsing
131
const withoutNumberParsing = parser(['--port', '3000'], {
132
  configuration: { 'parse-numbers': false }
133
});
134
console.log(withoutNumberParsing);
135
// Output: { _: [], port: '3000' }
136
```
137

138
### Parse Positional Numbers
139

140
Control automatic number parsing for positional arguments.
141

142
```typescript
143
// Default behavior (parse-positional-numbers: true)
144
const withPositionalNumbers = parser(['command', '42', '3.14']);
145
console.log(withPositionalNumbers);
146
// Output: { _: ['command', 42, 3.14] }
147

148
// Disabled positional number parsing
149
const withoutPositionalNumbers = parser(['command', '42'], {
150
  configuration: { 'parse-positional-numbers': false }
151
});
152
console.log(withoutPositionalNumbers);
153
// Output: { _: ['command', '42'] }
154
```
155

156
### Short Option Groups
157

158
Control parsing of combined short options like `-abc`.
159

160
```typescript
161
// Default behavior (short-option-groups: true)
162
const withGroups = parser(['-abc']);
163
console.log(withGroups);
164
// Output: { _: [], a: true, b: true, c: true }
165

166
// Disabled short option groups
167
const withoutGroups = parser(['-abc'], {
168
  configuration: { 'short-option-groups': false }
169
});
170
console.log(withoutGroups);
171
// Output: { _: [], abc: true }
172
```
173

174
### Duplicate Arguments Array
175

176
Control how duplicate arguments are handled.
177

178
```typescript
179
// Default behavior (duplicate-arguments-array: true)
180
const withArrays = parser(['--file', 'a.txt', '--file', 'b.txt']);
181
console.log(withArrays);
182
// Output: { _: [], file: ['a.txt', 'b.txt'] }
183

184
// Disabled duplicate arguments array
185
const withoutArrays = parser(['--file', 'a.txt', '--file', 'b.txt'], {
186
  configuration: { 'duplicate-arguments-array': false }
187
});
188
console.log(withoutArrays);
189
// Output: { _: [], file: 'b.txt' } (last value wins)
190
```
191

192
### Halt at Non-Option
193

194
Control whether parsing stops at first non-option argument.
195

196
```typescript
197
// Default behavior (halt-at-non-option: false)
198
const normal = parser(['--debug', 'command', '--verbose']);
199
console.log(normal);
200
// Output: { _: ['command'], debug: true, verbose: true }
201

202
// Halt at non-option enabled
203
const halting = parser(['--debug', 'command', '--verbose'], {
204
  configuration: { 'halt-at-non-option': true }
205
});
206
console.log(halting);
207
// Output: { _: ['command', '--verbose'], debug: true }
208
```
209

210
### Strip Aliased
211

212
Control whether alias keys are removed from results.
213

214
```typescript
215
const withAliases = parser(['-v'], {
216
  alias: { verbose: ['v'] }
217
});
218
console.log(withAliases);
219
// Output: { _: [], v: true, verbose: true }
220

221
const strippedAliases = parser(['-v'], {
222
  alias: { verbose: ['v'] },
223
  configuration: { 'strip-aliased': true }
224
});
225
console.log(strippedAliases);
226
// Output: { _: [], verbose: true } (alias 'v' removed)
227
```
228

229
### Strip Dashed
230

231
Control whether dashed keys are removed when camelCase versions exist.
232

233
```typescript
234
const withDashed = parser(['--foo-bar', 'value']);
235
console.log(withDashed);
236
// Output: { _: [], 'foo-bar': 'value', fooBar: 'value' }
237

238
const strippedDashed = parser(['--foo-bar', 'value'], {
239
  configuration: { 'strip-dashed': true }
240
});
241
console.log(strippedDashed);
242
// Output: { _: [], fooBar: 'value' } (dashed key removed)
243
```
244

245
### Unknown Options as Args
246

247
Control whether unknown options are treated as positional arguments.
248

249
```typescript
250
// Default behavior (unknown-options-as-args: false)
251
const normal = parser(['--known', '--unknown', 'value'], {
252
  boolean: ['known']
253
});
254
console.log(normal);
255
// Output: { _: [], known: true, unknown: 'value' }
256

257
// Unknown options as args
258
const asArgs = parser(['--known', '--unknown', 'value'], {
259
  boolean: ['known'],
260
  configuration: { 'unknown-options-as-args': true }
261
});
262
console.log(asArgs);
263
// Output: { _: ['--unknown', 'value'], known: true }
264
```
265

266
### Negation Prefix
267

268
Customize the prefix used for boolean negation.
269

270
```typescript
271
// Default negation prefix ('no-')
272
const defaultPrefix = parser(['--no-debug']);
273
console.log(defaultPrefix);
274
// Output: { _: [], debug: false }
275

276
// Custom negation prefix
277
const customPrefix = parser(['--disable-debug'], {
278
  configuration: { 'negation-prefix': 'disable-' }
279
});
280
console.log(customPrefix);
281
// Output: { _: [], debug: false }
282
```
283

284
### Combine Arrays
285

286
Control whether arrays are combined when provided by both command line and configuration files.
287

288
```typescript
289
// Default behavior (combine-arrays: false)
290
const withoutCombine = parser(['--tags', 'cli1', '--tags', 'cli2'], {
291
  configObjects: [{ tags: ['config1', 'config2'] }]
292
});
293
console.log(withoutCombine);
294
// Output: { _: [], tags: ['cli1', 'cli2'] } (config values ignored)
295

296
// Enabled combine arrays
297
const withCombine = parser(['--tags', 'cli1'], {
298
  configObjects: [{ tags: ['config1', 'config2'] }],
299
  configuration: { 'combine-arrays': true }
300
});
301
console.log(withCombine);
302
// Output: { _: [], tags: ['config1', 'config2', 'cli1'] } (arrays combined)
303
```
304

305
### Flatten Duplicate Arrays
306

307
Control whether array arguments are flattened when duplicated.
308

309
```typescript
310
// Default behavior (flatten-duplicate-arrays: true)
311
const flattened = parser(['--files', 'a.txt', 'b.txt', '--files', 'c.txt', 'd.txt'], {
312
  array: ['files']
313
});
314
console.log(flattened);
315
// Output: { _: [], files: ['a.txt', 'b.txt', 'c.txt', 'd.txt'] }
316

317
// Disabled flatten duplicate arrays
318
const notFlattened = parser(['--files', 'a.txt', 'b.txt', '--files', 'c.txt'], {
319
  array: ['files'],
320
  configuration: { 'flatten-duplicate-arrays': false }
321
});
322
console.log(notFlattened);
323
// Output: { _: [], files: [['a.txt', 'b.txt'], ['c.txt']] }
324
```
325

326
### Greedy Arrays
327

328
Control whether arrays consume multiple positional arguments following their flag.
329

330
```typescript
331
// Default behavior (greedy-arrays: true)
332
const greedy = parser(['--files', 'a.txt', 'b.txt', 'c.txt'], {
333
  array: ['files']
334
});
335
console.log(greedy);
336
// Output: { _: [], files: ['a.txt', 'b.txt', 'c.txt'] }
337

338
// Disabled greedy arrays
339
const notGreedy = parser(['--files', 'a.txt', 'b.txt', 'c.txt'], {
340
  array: ['files'],
341
  configuration: { 'greedy-arrays': false }
342
});
343
console.log(notGreedy);
344
// Output: { _: ['b.txt', 'c.txt'], files: ['a.txt'] }
345
```
346

347
### NArgs Eats Options
348

349
Control whether nargs consume dash options as well as positional arguments.
350

351
```typescript
352
// Default behavior (nargs-eats-options: false)
353
const normal = parser(['--input', 'file1.txt', '--output', 'result.txt'], {
354
  narg: { input: 2 }
355
});
356
console.log(normal);
357
// Output: { _: [], input: ['file1.txt'], output: 'result.txt' }
358

359
// Enabled nargs eats options
360
const eatsOptions = parser(['--input', 'file1.txt', '--output', 'result.txt'], {
361
  narg: { input: 2 },
362
  configuration: { 'nargs-eats-options': true }
363
});
364
console.log(eatsOptions);
365
// Output: { _: [], input: ['file1.txt', '--output'] }
366
```
367

368
### Populate Double Dash
369

370
Control whether unparsed flags are stored in `--` or `_`.
371

372
```typescript
373
// Default behavior (populate--: false)
374
const inUnderscore = parser(['cmd', '-a', '--', 'x', 'y']);
375
console.log(inUnderscore);
376
// Output: { _: ['cmd', 'x', 'y'], a: true }
377

378
// Enabled populate--
379
const inDoubleDash = parser(['cmd', '-a', '--', 'x', 'y'], {
380
  configuration: { 'populate--': true }
381
});
382
console.log(inDoubleDash);
383
// Output: { _: ['cmd'], '--': ['x', 'y'], a: true }
384
```
385

386
### Set Placeholder Key
387

388
Control whether a placeholder is added for keys not set via CLI arguments.
389

390
```typescript
391
// Default behavior (set-placeholder-key: false)
392
const normal = parser(['--name', 'Alice'], {
393
  string: ['name', 'email', 'phone']
394
});
395
console.log(normal);
396
// Output: { _: [], name: 'Alice' }
397

398
// Enabled set placeholder key
399
const withPlaceholders = parser(['--name', 'Alice'], {
400
  string: ['name', 'email', 'phone'],
401
  configuration: { 'set-placeholder-key': true }
402
});
403
console.log(withPlaceholders);
404
// Output: { _: [], name: 'Alice', email: undefined, phone: undefined }
405
```
406

407
## Combining Multiple Configuration Options
408

409
```typescript
410
const result = parser(['--foo-bar', 'value', '-abc', '--no-debug'], {
411
  configuration: {
412
    'camel-case-expansion': true,
413
    'short-option-groups': true,
414
    'boolean-negation': true,
415
    'parse-numbers': true,
416
    'dot-notation': true
417
  }
418
});
419
console.log(result);
420
// Output: { _: [], 'foo-bar': 'value', fooBar: 'value', a: true, b: true, c: true, debug: false }
421
```