0
# Core Parser Configuration
1

2
Primary yargs factory function and fundamental configuration methods for setting up argument parsing behavior.
3

4
## Capabilities
5

6
### Yargs Factory Function
7

8
Creates a new yargs parser instance with optional configuration.
9

10
```javascript { .api }
11
/**
12
 * Creates a new yargs parser instance
13
 * @param processArgs - Arguments to parse (default: [])
14
 * @param cwd - Current working directory  
15
 * @param parentRequire - Parent require function
16
 * @returns YargsInstance for method chaining
17
 */
18
function yargs(processArgs?: string | string[], cwd?: string, parentRequire?: Function): YargsInstance;
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
import yargs from 'yargs';
25
import { hideBin } from 'yargs/helpers';
26

27
// Parse process.argv (most common)
28
const argv1 = yargs(hideBin(process.argv)).parse();
29

30
// Parse custom arguments
31
const argv2 = yargs(['--port', '3000', '--verbose']).parse();
32

33
// Parse with custom working directory
34
const argv3 = yargs(hideBin(process.argv), '/custom/path').parse();
35
```
36

37
### Script Name Configuration
38

39
Configure how yargs identifies and displays the script name.
40

41
```javascript { .api }
42
/**
43
 * Set custom script name (overrides automatic detection)
44
 * @param scriptName - Custom script name to display
45
 * @returns YargsInstance for chaining
46
 */
47
scriptName(scriptName: string): YargsInstance;
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
yargs()
54
  .scriptName('my-tool')
55
  .help()
56
  .parse();
57
// Help will show "my-tool [options]" instead of auto-detected name
58
```
59

60
### Parser Configuration
61

62
Configure low-level parsing behavior.
63

64
```javascript { .api }
65
/**
66
 * Configure parser behavior with advanced options
67
 * @param config - Parser configuration object
68
 * @returns YargsInstance for chaining
69
 */
70
parserConfiguration(config: Configuration): YargsInstance;
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
yargs()
77
  .parserConfiguration({
78
    'duplicate-arguments-array': false,
79
    'flatten-duplicate-arrays': true,
80
    'populate--': true,
81
    'set-placeholder-key': true,
82
    'halt-at-non-option': false,
83
    'strip-aliased': false,
84
    'strip-dashed': false,
85
    'boolean-negation': true,
86
    'camel-case-expansion': true,
87
    'deep-merge-config': false,
88
    'sort-commands': false
89
  })
90
  .parse();
91
```
92

93
### Terminal Width
94

95
Control help text formatting based on terminal width.
96

97
```javascript { .api }
98
/**
99
 * Get current terminal width
100
 * @returns Terminal width in columns or null
101
 */
102
terminalWidth(): number | null;
103

104
/**
105
 * Set wrap width for help text formatting
106
 * @param cols - Number of columns to wrap at, or null for no wrapping
107
 * @returns YargsInstance for chaining
108
 */
109
wrap(cols: number | null): YargsInstance;
110
```
111

112
**Usage Examples:**
113

114
```javascript
115
const width = yargs().terminalWidth();
116
console.log(`Terminal width: ${width}`);
117

118
// Force wrap at 80 columns
119
yargs()
120
  .wrap(80)
121
  .help()
122
  .parse();
123

124
// Disable wrapping
125
yargs()
126
  .wrap(null)
127
  .help()
128
  .parse();
129
```
130

131
### Process Control
132

133
Control how yargs interacts with the process lifecycle.
134

135
```javascript { .api }
136
/**
137
 * Control whether yargs calls process.exit() on completion
138
 * @param enabled - Whether to exit process (default: true)
139
 * @returns YargsInstance for chaining
140
 */
141
exitProcess(enabled?: boolean): YargsInstance;
142

143
/**
144
 * Get current exit process setting
145
 * @returns Whether yargs will exit the process
146
 */
147
getExitProcess(): boolean;
148
```
149

150
**Usage Examples:**
151

152
```javascript
153
// Disable process exit (useful for testing)
154
yargs()
155
  .exitProcess(false)
156
  .help()
157
  .parse();
158

159
// Check current setting
160
const willExit = yargs().getExitProcess();
161
```
162

163
### Configuration Objects
164

165
Load configuration from objects or package.json.
166

167
```javascript { .api }
168
/**
169
 * Load configuration from package.json
170
 * @param key - Key in package.json to read config from
171
 * @param rootPath - Root path for package.json search
172
 * @returns YargsInstance for chaining
173
 */
174
pkgConf(key: string, rootPath?: string): YargsInstance;
175
```
176

177
**Usage Examples:**
178

179
```javascript
180
// Load config from package.json "myapp" field
181
yargs()
182
  .pkgConf('myapp')
183
  .parse();
184

185
// package.json:
186
// {
187
//   "myapp": {
188
//     "port": 3000,
189
//     "verbose": true
190
//   }
191
// }
192
```
193

194
## Types
195

196
```javascript { .api }
197
/**
198
 * Parser configuration options
199
 */
200
interface Configuration {
201
  /** Create array for duplicate arguments */
202
  'duplicate-arguments-array'?: boolean;
203
  /** Flatten duplicate arrays */
204
  'flatten-duplicate-arrays'?: boolean;
205
  /** Populate -- with remaining args */
206
  'populate--'?: boolean;
207
  /** Set placeholder key for missing options */
208
  'set-placeholder-key'?: boolean;
209
  /** Stop parsing at first non-option */
210
  'halt-at-non-option'?: boolean;
211
  /** Remove aliased keys from result */
212
  'strip-aliased'?: boolean;
213
  /** Remove dashed keys from result */
214
  'strip-dashed'?: boolean;
215
  /** Enable --no-flag negation */
216
  'boolean-negation'?: boolean;
217
  /** Convert kebab-case to camelCase */
218
  'camel-case-expansion'?: boolean;
219
  /** Deep merge config objects */
220
  'deep-merge-config'?: boolean;
221
  /** Sort commands in help */
222
  'sort-commands'?: boolean;
223
  /** Parse positional numbers */
224
  'parse-positional-numbers'?: boolean;
225
}
226
```