0
# Options and Configuration
1

2
Option flag system with aliases, descriptions, default values, and program-level configuration.
3

4
## Capabilities
5

6
### Option Method
7

8
Add option flags to commands with support for aliases, descriptions, and default values.
9

10
```javascript { .api }
11
/**
12
 * Add option flag to current command or global scope
13
 * @param {string} flags - Flag pattern (e.g., '-f, --force' or '--verbose')
14
 * @param {string} [desc] - Option description
15
 * @param {*} [value] - Default value (enables type casting)
16
 * @returns {Sade} Chainable instance
17
 */
18
option(flags, desc, value);
19
```
20

21
**Parameters:**
22

23
- `flags` (string, required): Flag pattern with optional alias
24
  - Short and long flags: `-f, --force` or `--force, -f`
25
  - Long flag only: `--verbose`
26
  - Short flag only: `-v`
27
  - Separator: comma `,` or space ` `
28
- `desc` (string, optional): Human-readable description for help text
29
- `value` (any, optional): Default value (enables type casting via mri)
30

31
**Usage Examples:**
32

33
```javascript
34
// Boolean flags (default to false, true when present)
35
prog.option('-v, --verbose', 'Enable verbose output');
36
prog.option('--debug', 'Enable debug mode');
37

38
// String options with defaults
39
prog.option('-c, --config', 'Configuration file path', 'config.json');
40
prog.option('--output', 'Output directory', './dist');
41

42
// Number options with defaults  
43
prog.option('-p, --port', 'Server port', 3000);
44
prog.option('--timeout', 'Request timeout in ms', 5000);
45

46
// Global options (apply to all commands)
47
const prog = sade('my-cli');
48
prog.option('-g, --global', 'Global flag available to all commands');
49

50
prog.command('build')
51
  .option('-w, --watch', 'Watch for changes')  // Only for 'build' command
52
  .action((opts) => {
53
    // opts.global available here
54
    // opts.watch available here
55
  });
56
```
57

58
### Flag Patterns and Aliases
59

60
Options support various flag pattern formats with automatic alias detection.
61

62
**Flag Pattern Examples:**
63

64
```javascript
65
// Standard patterns
66
prog.option('-f, --force');         // Short: -f, Long: --force
67
prog.option('--force, -f');         // Same as above (order doesn't matter)
68
prog.option('-f --force');          // Space separator instead of comma
69
prog.option('--force -f');          // Long flag first
70

71
// Single flags
72
prog.option('--verbose');           // Long flag only
73
prog.option('-v');                  // Short flag only (less common)
74

75
// Complex names
76
prog.option('--dry-run');           // Hyphenated long flag
77
prog.option('-n, --dry-run');       // With short alias
78
```
79

80
**Access in Action Handlers:**
81

82
```javascript
83
prog.command('deploy')
84
  .option('-f, --force', 'Force deployment')
85
  .option('--dry-run', 'Show what would be deployed')
86
  .action((opts) => {
87
    console.log(opts.force);     // true if -f or --force used
88
    console.log(opts.f);         // Same as opts.force (alias)
89
    console.log(opts['dry-run']); // true if --dry-run used
90
    console.log(opts.dryRun);    // undefined (not auto-converted)
91
  });
92
```
93

94
### Default Values and Type Casting
95

96
Default values enable automatic type casting based on the provided value type.
97

98
```javascript { .api }
99
// Type casting examples
100
prog.option('-p, --port', 'Server port', 3000);        // Number
101
prog.option('-c, --config', 'Config file', 'app.json'); // String  
102
prog.option('--debug', 'Debug mode', false);           // Boolean
103
prog.option('--max-files', 'Max files', 100);          // Number
104
```
105

106
**Type Casting Behavior:**
107

108
```javascript
109
// Command: my-cli --port 8080 --debug --config custom.json
110
prog.command('start')
111
  .option('-p, --port', 'Server port', 3000)
112
  .option('--debug', 'Debug mode', false)
113
  .option('-c, --config', 'Config file', 'app.json')
114
  .action((opts) => {
115
    console.log(typeof opts.port);    // "number" (8080)
116
    console.log(typeof opts.debug);   // "boolean" (true)
117
    console.log(typeof opts.config);  // "string" ("custom.json")
118
  });
119
```
120

121
### Version Method
122

123
Set the program version for automatic `--version` flag handling.
124

125
```javascript { .api }
126
/**
127
 * Set program version for --version flag
128
 * @param {string} str - Version string
129
 * @returns {Sade} Chainable instance
130
 */
131
version(str);
132
```
133

134
**Usage Examples:**
135

136
```javascript
137
// Set version from package.json
138
const pkg = require('./package.json');
139
prog.version(pkg.version);
140

141
// Or set manually
142
prog.version('1.0.0');
143

144
// Automatically enables --version and -v flags
145
// $ my-cli --version
146
// my-cli, 1.0.0
147
```
148

149
### Example Method
150

151
Add usage examples to commands for better help documentation.
152

153
```javascript { .api }
154
/**
155
 * Add usage example to current command
156
 * @param {string} str - Example usage string (without program name)
157
 * @returns {Sade} Chainable instance
158
 */
159
example(str);
160
```
161

162
**Parameters:**
163

164
- `str` (string, required): Example usage string (program name is automatically prepended)
165

166
**Usage Examples:**
167

168
```javascript
169
prog.command('build <src> <dest>')
170
  .describe('Build source to destination')
171
  .option('-w, --watch', 'Watch for changes')
172
  .option('-m, --minify', 'Minify output')
173
  .example('build src dist')
174
  .example('build src dist --watch')
175
  .example('build app public --minify --watch');
176
```
177

178
**Help Output:**
179
```
180
  Examples
181
    $ my-cli build src dist
182
    $ my-cli build src dist --watch  
183
    $ my-cli build app public --minify --watch
184
```
185

186
### Global vs Command Options
187

188
Options can be defined at different scopes depending on when they are added.
189

190
**Global Options (before any commands):**
191

192
```javascript
193
const prog = sade('my-cli');
194

195
// These apply to ALL commands
196
prog.option('-v, --verbose', 'Verbose output');
197
prog.option('-c, --config', 'Config file', 'config.json');
198

199
prog.command('build')
200
  .action((opts) => {
201
    // opts.verbose and opts.config available here
202
  });
203

204
prog.command('test')  
205
  .action((opts) => {
206
    // opts.verbose and opts.config available here too
207
  });
208
```
209

210
**Command-Specific Options:**
211

212
```javascript
213
prog.command('build <src>')
214
  .option('-w, --watch', 'Watch mode')  // Only for 'build' command
215
  .action((src, opts) => {
216
    // opts.watch only available in 'build' command
217
  });
218

219
prog.command('test')
220
  .action((opts) => {
221
    // opts.watch NOT available here
222
  });
223
```
224

225
**Option Inheritance and Merging:**
226

227
Options are merged in this order (later values override earlier ones):
228
1. Global options (defined before any commands)
229
2. Command-specific options  
230
3. Parse-time options (passed to `parse()` method)
231

232
### Built-in Options
233

234
Sade automatically provides standard CLI options:
235

236
- `--help, -h`: Display help text (always available)
237
- `--version, -v`: Display version (only if version is set)
238

239
These are automatically added to help output and cannot be overridden.