0
# Command Line Interface API
1

2
Complete CLI for batch analysis, CI/CD integration, and automated reporting workflows. The CLI provides programmatic access to command-line functionality and configuration.
3

4
## Capabilities
5

6
### CLI Execution Function
7

8
Execute CLI analysis with programmatic override options.
9

10
```javascript { .api }
11
/**
12
 * Execute CLI analysis with programmatic override options
13
 * @param {Object} options - Override CLI options (optional)
14
 * @param {Function} done - Completion callback (optional)
15
 */
16
function exec(options, done);
17
```
18

19
**Parameters:**
20

21
- `options` (Object, optional): Override CLI options
22
- `done` (Function, optional): Completion callback
23

24
**Usage Examples:**
25

26
```javascript
27
const cli = require('plato/lib/cli');
28

29
// Execute with default CLI options
30
cli.exec();
31

32
// Execute with custom options
33
cli.exec({
34
  title: 'Custom Analysis',
35
  recurse: true,
36
  quiet: false
37
}, function() {
38
  console.log('CLI analysis completed');
39
});
40

41
// Access parsed CLI arguments
42
console.log('CLI args:', cli.args);
43
console.log('CLI options:', cli.options);
44
```
45

46
### CLI Configuration Access
47

48
Access to CLI options configuration and parsed command-line arguments.
49

50
```javascript { .api }
51
/** CLI options configuration object */
52
const options: Object;
53

54
/** Parsed command-line arguments object */
55
const args: Object;
56
```
57

58
**Properties:**
59

60
- `options` (Object): CLI options configuration object
61
- `args` (Object): Parsed command-line arguments object
62

63
## Command Line Options
64

65
The CLI supports the following command-line options:
66

67
### Help and Version
68

69
```bash
70
plato -h, --help        # Display help text
71
plato -v, --version     # Print version information
72
```
73

74
### Analysis Configuration
75

76
```bash
77
plato -d, --dir <String>          # Output directory for reports (required)
78
plato -t, --title <String>        # Custom report title
79
plato -r, --recurse               # Recursively search directories
80
plato -q, --quiet                 # Reduce output to errors only
81
plato -n, --noempty               # Skip empty lines from line count
82
```
83

84
### File Filtering
85

86
```bash
87
plato -x, --exclude <String>      # File exclusion regex pattern
88
```
89

90
### Linting Integration
91

92
```bash
93
plato -l, --jshint <String>       # JSHint configuration file path
94
plato -e, --eslint <String>       # ESLint configuration file path
95
```
96

97
### Report Customization
98

99
```bash
100
plato -D, --date <String>         # Custom report date
101
```
102

103
## CLI Usage Examples
104

105
### Basic Analysis
106

107
```bash
108
# Analyze all JavaScript files in src directory
109
plato -r -d reports src
110

111
# Analyze specific files with custom title
112
plato -d reports -t "My Project Analysis" src/app.js src/utils.js
113
```
114

115
### Advanced Configuration
116

117
```bash
118
# Exclude test files and node_modules
119
plato -r -d reports -x "test|spec|node_modules" src
120

121
# Use custom JSHint configuration
122
plato -r -d reports -l .jshintrc src
123

124
# Quiet mode for CI/CD
125
plato -r -d reports -q src
126
```
127

128
### Integration Examples
129

130
```bash
131
# CI/CD pipeline usage
132
plato -r -d build/reports -q -t "Build $BUILD_NUMBER" src
133
if [ $? -eq 0 ]; then
134
  echo "Code analysis passed"
135
else
136
  echo "Code analysis failed"
137
  exit 1
138
fi
139

140
# Generate reports with timestamp
141
plato -r -d "reports-$(date +%Y%m%d)" -t "Daily Analysis" src
142
```
143

144
## Programmatic CLI Options
145

146
When using the `exec()` function programmatically, you can override CLI options:
147

148
```javascript { .api }
149
interface CLIOptions {
150
  /** Output directory path */
151
  dir?: string;
152
  /** Report title */
153
  title?: string;
154
  /** Recursively search directories */
155
  recurse?: boolean;
156
  /** Quiet mode */
157
  quiet?: boolean;
158
  /** Skip empty lines */
159
  noempty?: boolean;
160
  /** File exclusion regex */
161
  exclude?: string;
162
  /** JSHint config file path */
163
  jshint?: string;
164
  /** ESLint config file path */
165
  eslint?: string;
166
  /** Custom report date */
167
  date?: string;
168
  /** File paths to analyze */
169
  files?: string[];
170
}
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
const cli = require('plato/lib/cli');
177

178
// Override CLI options programmatically
179
cli.exec({
180
  dir: 'custom-reports',
181
  title: 'Automated Analysis',
182
  recurse: true,
183
  quiet: true,
184
  files: ['src/**/*.js']
185
}, function() {
186
  console.log('Analysis complete');
187
});
188
```
189

190
## Binary Entry Point
191

192
The main executable is located at `bin/plato` and provides the command-line interface:
193

194
```javascript { .api }
195
/** Main CLI executable that delegates to lib/cli.js */
196
// Handles version (-v) and help (-h) flags
197
// Calls cli.exec() for main functionality
198
```
199

200
**Direct Execution:**
201

202
```bash
203
# Using global installation
204
plato -r -d reports src
205

206
# Using npx
207
npx plato -r -d reports src
208

209
# Using local installation
210
./node_modules/.bin/plato -r -d reports src
211
```
212

213
## Info Module Integration
214

215
The CLI integrates with the info module for version and help display:
216

217
```javascript { .api }
218
/** Package name constant */
219
const name: string;
220

221
/** Print version to console */
222
function version(): void;
223

224
/** Print help text to console */
225
function help(): void;
226
```
227

228
**Usage in CLI context:**
229

230
```bash
231
plato --version    # Calls info.version()
232
plato --help       # Calls info.help()
233
```
234

235
## Exit Codes
236

237
The CLI uses standard exit codes for automation and CI/CD integration:
238

239
- `0`: Analysis completed successfully
240
- `1`: Analysis failed due to errors
241
- `2`: Invalid command-line arguments
242

243
**CI/CD Integration:**
244

245
```bash
246
# Bash script example
247
plato -r -d reports -q src
248
exit_code=$?
249

250
if [ $exit_code -eq 0 ]; then
251
  echo "✓ Code analysis passed"
252
  # Continue with deployment
253
else
254
  echo "✗ Code analysis failed (exit code: $exit_code)"
255
  exit $exit_code
256
fi
257
```