0
# Help System
1

2
Automated help text generation and display system with support for general help, command-specific help, and custom formatting.
3

4
## Capabilities
5

6
### Help Method
7

8
Display formatted help text for specific commands or general program help.
9

10
```javascript { .api }
11
/**
12
 * Display help text for command or general help
13
 * @param {string} [cmd] - Command name for specific help, omit for general help
14
 * @returns {void} Prints formatted help to console
15
 */
16
help(cmd);
17
```
18

19
**Parameters:**
20

21
- `cmd` (string, optional): Command name to show help for
22
  - If omitted: Shows general program help with command list
23
  - If provided: Shows detailed help for that specific command
24

25
**Usage Examples:**
26

27
```javascript
28
// Show general help (same as --help flag)
29
prog.help();
30

31
// Show help for specific command
32
prog.help('build');
33
prog.help('remote add');  // For subcommands
34

35
// Programmatic help display
36
if (someCondition) {
37
  prog.help('deploy');
38
  process.exit(0);
39
}
40
```
41

42
### Automatic Help Integration
43

44
Help functionality is automatically integrated into the CLI with built-in flags.
45

46
**Built-in Help Flags:**
47

48
- `--help, -h`: Available on all commands and global scope
49
- Automatically added to options list in help output
50
- Takes precedence over command execution
51

52
**Usage Examples:**
53

54
```javascript
55
// These all trigger help display:
56
// $ my-cli --help          (general help)
57
// $ my-cli -h              (general help)  
58
// $ my-cli build --help    (build command help)
59
// $ my-cli build -h        (build command help)
60
```
61

62
### General Help Format
63

64
General help shows program overview and available commands.
65

66
**General Help Structure:**
67

68
```text
69
  Description
70
    [Program description if set via describe()]
71

72
  Usage  
73
    $ program-name <command> [options]
74

75
  Available Commands
76
    command1    First line of command description
77
    command2    First line of command description
78
    
79
  For more info, run any command with the `--help` flag
80
    $ program-name command1 --help
81
    $ program-name command2 --help
82

83
  Options
84
    -v, --version    Displays current version
85
    -g, --global     Global option description
86
    -h, --help       Displays this message
87
```
88

89
**Example:**
90

91
```javascript
92
const prog = sade('git-cli');
93

94
prog.describe('A simple git-like CLI tool');
95
prog.option('-v, --verbose', 'Enable verbose output');
96

97
prog.command('add <files..>', 'Add files to staging area');
98
prog.command('commit', 'Commit staged changes');
99

100
prog.help(); // Shows general help
101
```
102

103
**Output:**
104
```text
105
  Description
106
    A simple git-like CLI tool
107

108
  Usage
109
    $ git-cli <command> [options]
110

111
  Available Commands
112
    add       Add files to staging area
113
    commit    Commit staged changes
114

115
  For more info, run any command with the `--help` flag
116
    $ git-cli add --help
117
    $ git-cli commit --help
118

119
  Options
120
    -v, --version    Displays current version
121
    -v, --verbose    Enable verbose output  
122
    -h, --help       Displays this message
123
```
124

125
### Command-Specific Help Format
126

127
Command-specific help shows detailed information for individual commands.
128

129
**Command Help Structure:**
130

131
```text
132
  Description
133
    [Full command description with all sentences]
134

135
  Usage
136
    $ program-name command <args> [options]
137

138
  Aliases (if any)
139
    $ program-name alias1
140
    $ program-name alias2
141

142
  Options
143
    -o, --option     Option description  (default value)
144
    -g, --global     Global option description
145
    -h, --help       Displays this message
146

147
  Examples (if any)
148
    $ program-name command example1
149
    $ program-name command example2 --option
150
```
151

152
**Example:**
153

154
```javascript
155
prog.command('deploy <env> [version]')
156
  .describe([
157
    'Deploy application to specified environment.',
158
    'This will build the application and upload it to the target environment.',
159
    'Make sure all tests pass before deploying to production.'
160
  ])
161
  .alias('d', 'ship')
162
  .option('-f, --force', 'Force deployment without confirmation')
163
  .option('--timeout', 'Deployment timeout in seconds', 300)
164
  .example('deploy staging')  
165
  .example('deploy prod v1.2.0 --force')
166
  .example('deploy staging --timeout 600');
167

168
prog.help('deploy');
169
```
170

171
**Output:**
172
```text
173
  Description
174
    Deploy application to specified environment.
175
    This will build the application and upload it to the target environment.
176
    Make sure all tests pass before deploying to production.
177

178
  Usage
179
    $ my-cli deploy <env> [version] [options]
180

181
  Aliases
182
    $ my-cli d
183
    $ my-cli ship
184

185
  Options
186
    -f, --force      Force deployment without confirmation
187
    --timeout        Deployment timeout in seconds  (default 300)
188
    -g, --global     Global option description
189
    -h, --help       Displays this message
190

191
  Examples
192
    $ my-cli deploy staging
193
    $ my-cli deploy prod v1.2.0 --force
194
    $ my-cli deploy staging --timeout 600
195
```
196

197
### Single Command Mode Help
198

199
Single command mode provides simplified help output without command selection.
200

201
**Single Command Help Features:**
202

203
- No "Available Commands" section
204
- No "For more info..." text
205
- Direct usage pattern in program name
206
- Simplified structure focused on the single command
207

208
**Example:**
209

210
```javascript
211
const prog = sade('serve [dir] [port]', true);
212

213
prog.describe('Start a static file server')
214
  .option('-p, --port', 'Server port', 3000)
215
  .option('-h, --host', 'Server host', 'localhost')
216
  .example('serve')
217
  .example('serve ./public')
218
  .example('serve ./dist 8080');
219

220
prog.help();
221
```
222

223
**Output:**
224
```text
225
  Description
226
    Start a static file server
227

228
  Usage
229
    $ serve [dir] [port] [options]
230

231
  Options
232
    -p, --port       Server port  (default 3000)
233
    -h, --host       Server host  (default localhost)
234
    -v, --version    Displays current version
235
    -h, --help       Displays this message
236

237
  Examples
238
    $ serve
239
    $ serve ./public  
240
    $ serve ./dist 8080
241
```
242

243
### Help Text Customization
244

245
Help output can be customized through various methods during command definition.
246

247
**Description Customization:**
248

249
```javascript
250
// Single line (appears in both general and command help)
251
prog.command('build').describe('Build the application');
252

253
// Multiple sentences (first line in general, all lines in command help)
254
prog.command('test').describe([
255
  'Run the test suite',           // Appears in general help
256
  'Executes all test files',      // Only in command help
257
  'Generates coverage report'     // Only in command help  
258
]);
259

260
// Automatic sentence splitting
261
prog.command('lint').describe('Check code style. Reports formatting issues and suggests fixes.');
262
```
263

264
**Example Organization:**
265

266
```javascript
267
// Add multiple examples for better documentation
268
prog.command('docker run <image>')
269
  .example('run nginx')
270
  .example('run nginx:latest')  
271
  .example('run -p 8080:80 nginx')
272
  .example('run -d --name web nginx');
273
```
274

275
### Error Integration
276

277
Help system integrates with error handling to provide contextual assistance.
278

279
**Error + Help Pattern:**
280

281
When commands fail, Sade automatically suggests using help:
282

283
```text
284
  ERROR
285
    Insufficient arguments!
286

287
  Run `$ my-cli build --help` for more info.
288
```
289

290
**Custom Error Handling:**
291

292
```javascript
293
prog.command('deploy <env>')
294
  .action((env, opts) => {
295
    if (!['dev', 'staging', 'prod'].includes(env)) {
296
      console.error(`Invalid environment: ${env}`);
297
      prog.help('deploy');  // Show command help
298
      process.exit(1);
299
    }
300
  });
301
```