0
# Command-Line Interface
1

2
JSDoc's command-line interface provides comprehensive control over documentation generation through the main `jsdoc` command and its options. The CLI module is internal and not intended for programmatic use.
3

4
## Capabilities
5

6
### Command Execution
7

8
The JSDoc CLI is primarily designed for command-line usage rather than programmatic access.
9

10
```bash
11
# Primary command interface
12
jsdoc [options] <source files>
13
```
14

15
**Important Note**: The CLI module (`cli.js`) is marked as private and is not designed for external programmatic use. For programmatic access to JSDoc functionality, use the core modules directly:
16

17
```javascript
18
// Programmatic usage - use core modules instead of CLI
19
const parser = require('jsdoc/src/parser');
20
const env = require('jsdoc/env');
21
const Config = require('jsdoc/config');
22
```
23

24
### Internal Implementation
25

26
The CLI module contains internal functions that handle the documentation generation workflow, but these are not part of the public API. External users should use the command-line interface or the core modules for programmatic access.
27

28
## Command-Line Options
29

30
### Basic Options
31

32
```bash
33
# Help and version
34
jsdoc --help                    # Display help message
35
jsdoc --version                 # Display version information
36

37
# Input and output
38
jsdoc file1.js file2.js         # Process specific files
39
jsdoc --destination ./docs      # Output directory (default: ./out/)
40
jsdoc --recurse                 # Recurse into subdirectories
41
```
42

43
### Configuration Options
44

45
```bash
46
# Configuration file
47
jsdoc --configure conf.json     # Use custom configuration file
48
jsdoc --encoding utf8           # File encoding (default: utf8)
49

50
# Package and README
51
jsdoc --package package.json    # Package file path
52
jsdoc --readme README.md        # README file path
53
```
54

55
### Template and Plugin Options
56

57
```bash
58
# Template selection
59
jsdoc --template ./my-template  # Custom template directory
60

61
# Access control
62
jsdoc --access public           # Show only public symbols
63
jsdoc --private                 # Include private symbols
64
```
65

66
### Debug and Logging Options
67

68
```bash
69
# Debugging
70
jsdoc --debug                   # Enable debug logging
71
jsdoc --verbose                 # Enable verbose logging
72
jsdoc --pedantic                # Treat warnings as errors
73
jsdoc --explain                 # Dump doclet internals
74
```
75

76
### Testing Options
77

78
```bash
79
# Testing
80
jsdoc --test                    # Run test suite
81
jsdoc --match pattern           # Filter tests by pattern
82
jsdoc --nocolor                 # Disable colored output
83
```
84

85
## Usage Examples
86

87
### Basic Documentation Generation
88

89
```bash
90
# Single file
91
jsdoc mylib.js
92

93
# Multiple files
94
jsdoc src/core.js src/utils.js src/api.js 
95

96
# Directory with recursion
97
jsdoc --recurse src/
98

99
# Custom output directory
100
jsdoc --recurse src/ --destination docs/
101
```
102

103
### Advanced Configuration
104

105
```bash
106
# With configuration file
107
jsdoc --configure jsdoc.conf.json src/
108

109
# With custom template
110
jsdoc --template templates/custom src/ --destination public/docs/
111

112
# Include private members
113
jsdoc --private --access all src/
114
```
115

116
### Development and Debugging
117

118
```bash
119
# Debug mode with verbose output
120
jsdoc --debug --verbose src/
121

122
# Dump internal doclet data
123
jsdoc --explain src/core.js
124

125
# Run tests
126
jsdoc --test
127
```
128

129
## Integration Patterns
130

131
### Package.json Scripts
132

133
```json
134
{
135
  "scripts": {
136
    "docs": "jsdoc --configure jsdoc.conf.json --destination docs/ src/",
137
    "docs:watch": "nodemon --exec 'npm run docs' --watch src/",
138
    "docs:serve": "npm run docs && http-server docs/"
139
  }
140
}
141
```
142

143
### Build Tool Integration
144

145
```javascript
146
// Gulp integration
147
const { spawn } = require('child_process');
148

149
function generateDocs() {
150
  return spawn('jsdoc', [
151
    '--configure', 'jsdoc.conf.json',
152
    '--destination', 'dist/docs/',
153
    'src/'
154
  ], { stdio: 'inherit' });
155
}
156
```
157

158
### CI/CD Pipeline
159

160
```yaml
161
# GitHub Actions example
162
- name: Generate Documentation
163
  run: |
164
    npm install -g jsdoc
165
    jsdoc --configure jsdoc.conf.json --destination docs/ src/
166
    
167
- name: Deploy Documentation
168
  uses: peaceiris/actions-gh-pages@v3
169
  with:
170
    github_token: ${{ secrets.GITHUB_TOKEN }}
171
    publish_dir: ./docs
172
```
173

174
## Error Handling
175

176
### Common Exit Codes
177

178
- `0`: Success
179
- `1`: General error (parsing, configuration, or generation failure)
180

181
### Error Categories
182

183
- **Configuration Errors**: Invalid config file, missing template
184
- **Parsing Errors**: Syntax errors in source files, invalid JSDoc comments
185
- **Generation Errors**: Template errors, file system issues
186
- **Plugin Errors**: Plugin loading failures, plugin execution errors
187

188
### Debug Techniques
189

190
```bash
191
# Enable debug logging
192
jsdoc --debug --verbose src/
193

194
# Dump doclet internals
195
jsdoc --explain src/problematic-file.js
196

197
# Pedantic mode (warnings as errors)
198
jsdoc --pedantic src/
199
```