0
# CLI Interface
1

2
Full-featured command-line interface built with Click framework supporting extensive configuration options, multiple output formats, and integration with CI/CD pipelines. The CLI provides the primary way to use interrogate for analyzing docstring coverage.
3

4
## Capabilities
5

6
### Main CLI Function
7

8
Primary command-line entry point that handles argument parsing and execution.
9

10
```python { .api }
11
def main(
12
    ctx: click.Context,
13
    paths: Tuple[str, ...],
14
    color: bool = True,
15
    exclude: Tuple[str, ...] = (),
16
    ignore_init_method: bool = False,
17
    ignore_init_module: bool = False,
18
    ignore_magic: bool = False,
19
    ignore_module: bool = False,
20
    ignore_nested_classes: bool = False,
21
    ignore_nested_functions: bool = False,
22
    ignore_private: bool = False,
23
    ignore_property_decorators: bool = False,
24
    ignore_regex: Tuple[str, ...] = (),
25
    ignore_semiprivate: bool = False,
26
    fail_under: Optional[float] = None,
27
    docstring_style: str = "sphinx",
28
    output: Optional[str] = None,
29
    quiet: int = 0,
30
    verbose: int = 0,
31
    omit_covered_files: bool = False,
32
    generate_badge: Optional[str] = None,
33
    badge_format: str = "svg",
34
    badge_style: str = "flat",
35
    config: Optional[str] = None
36
) -> None:
37
    """
38
    Main CLI command for interrogate.
39
    
40
    Args:
41
        ctx: Click context object
42
        paths: Paths to analyze for docstring coverage
43
        color: Use color output
44
        exclude: Patterns of paths to exclude
45
        ignore_init_method: Ignore __init__ method docstrings
46
        ignore_init_module: Ignore __init__.py module docstrings  
47
        ignore_magic: Ignore magic method docstrings
48
        ignore_module: Ignore module-level docstrings
49
        ignore_nested_classes: Ignore nested class docstrings
50
        ignore_nested_functions: Ignore nested function docstrings
51
        ignore_private: Ignore private method docstrings
52
        ignore_property_decorators: Ignore property decorator docstrings
53
        ignore_regex: Regular expressions for names to ignore
54
        ignore_semiprivate: Ignore semiprivate method docstrings
55
        fail_under: Fail if coverage percentage is below this threshold
56
        docstring_style: Docstring style to check
57
        output: Output file path
58
        quiet: Quiet level (0-2)
59
        verbose: Verbose level (0-2)
60
        omit_covered_files: Don't show files with 100% coverage
61
        generate_badge: Path to generate coverage badge
62
        badge_format: Badge format (svg/png)
63
        badge_style: Badge style
64
        config: Configuration file path
65
    """
66
```
67

68
## Command Line Options
69

70
### Analysis Options
71

72
Options controlling what code elements to analyze and ignore.
73

74
```bash
75
# Ignore specific types of code elements
76
interrogate --ignore-init-method src/           # Ignore __init__ methods
77
interrogate --ignore-init-module src/           # Ignore __init__.py modules
78
interrogate --ignore-magic src/                 # Ignore magic methods (__str__, etc.)
79
interrogate --ignore-module src/                # Ignore module-level docstrings
80
interrogate --ignore-nested-classes src/        # Ignore nested classes
81
interrogate --ignore-nested-functions src/      # Ignore nested functions
82
interrogate --ignore-private src/               # Ignore private methods (_method)
83
interrogate --ignore-semiprivate src/           # Ignore semiprivate methods (_method)
84
interrogate --ignore-property-decorators src/   # Ignore @property decorators
85
interrogate --ignore-setters src/               # Ignore @property.setter methods
86
interrogate --ignore-overloaded-functions src/  # Ignore @typing.overload functions
87
```
88

89
### Pattern-Based Filtering
90

91
Options for filtering files and code elements using patterns.
92

93
```bash
94
# Exclude files/directories by pattern
95
interrogate --exclude tests --exclude docs src/
96

97
# Ignore code elements by regex pattern
98
interrogate --ignore-regex "test_.*" --ignore-regex ".*_test$" src/
99

100
# Include only specific patterns (whitelist)
101
interrogate --whitelist-regex "^public_.*" --whitelist-regex "^api_.*" src/
102

103
# Include .pyi stub files
104
interrogate --ext pyi src/
105

106
# Combine multiple patterns
107
interrogate --ignore-regex "^get_.*" --ignore-regex "^set_.*" --ignore-regex "test_.*" src/
108
```
109

110
### Output Control
111

112
Options controlling output format and verbosity.
113

114
```bash
115
# Verbose output with detailed information
116
interrogate --verbose src/                      # Show detailed results
117
interrogate -vv src/                           # Very verbose output
118

119
# Quiet output
120
interrogate --quiet src/                       # Suppress detailed output  
121
interrogate -qq src/                          # Very quiet (minimal output)
122

123
# Disable colored output
124
interrogate --no-color src/
125

126
# Omit files with 100% coverage from detailed output
127
interrogate --omit-covered-files src/
128

129
# Save output to file
130
interrogate --output results.txt src/
131
```
132

133
### Quality Control
134

135
Options for enforcing coverage standards and failing builds.
136

137
```bash
138
# Fail if coverage below threshold
139
interrogate --fail-under 80 src/               # Require 80% coverage
140
interrogate --fail-under 95.5 src/             # Require 95.5% coverage
141

142
# Different docstring styles (affects validation)
143
interrogate --docstring-style sphinx src/      # Sphinx style (default)
144
interrogate --docstring-style google src/      # Google style
145
interrogate --docstring-style numpy src/       # NumPy style
146
```
147

148
### Badge Generation
149

150
Options for generating coverage badges.
151

152
```bash
153
# Generate SVG badge in current directory
154
interrogate --generate-badge . src/
155

156
# Generate badge with specific filename
157
interrogate --generate-badge docs/coverage.svg src/
158

159
# Generate PNG badge (requires cairosvg)
160
interrogate --generate-badge docs/coverage.png --badge-format png src/
161

162
# Different badge styles
163
interrogate --generate-badge . --badge-style flat src/           # Default flat style
164
interrogate --generate-badge . --badge-style flat-square src/    # Flat square style
165
interrogate --generate-badge . --badge-style for-the-badge src/  # For-the-badge style
166
interrogate --generate-badge . --badge-style plastic src/        # Plastic style
167
```
168

169
### Configuration Files
170

171
Options for using configuration files.
172

173
```bash
174
# Use specific configuration file
175
interrogate --config pyproject.toml src/
176
interrogate --config setup.cfg src/
177

178
# Configuration file auto-discovery (default behavior)
179
# Searches for pyproject.toml or setup.cfg in project root
180
interrogate src/
181
```
182

183
## Usage Examples
184

185
### Basic Usage
186

187
```bash
188
# Analyze current directory
189
interrogate .
190

191
# Analyze specific directories
192
interrogate src/ tests/
193

194
# Analyze specific files
195
interrogate src/main.py src/utils.py
196
```
197

198
### Common CI/CD Patterns
199

200
```bash
201
# Strict coverage check for CI
202
interrogate --fail-under 85 --ignore-init-method --ignore-private src/
203

204
# Generate badge and check coverage
205
interrogate --generate-badge docs/coverage.svg --fail-under 80 src/
206

207
# Quiet mode for CI with specific threshold
208
interrogate --quiet --fail-under 90 --omit-covered-files src/
209
```
210

211
### Development Workflow
212

213
```bash
214
# Detailed analysis during development
215
interrogate --verbose --color src/
216

217
# Focus on missing docstrings only
218
interrogate --verbose --omit-covered-files src/
219

220
# Check specific patterns
221
interrogate --ignore-regex "test_.*" --ignore-private --verbose src/
222
```
223

224
### Complex Configuration
225

226
```bash
227
# Comprehensive configuration
228
interrogate \
229
  --fail-under 85 \
230
  --ignore-init-method \
231
  --ignore-private \
232
  --ignore-magic \
233
  --ignore-regex "test_.*" \
234
  --ignore-regex ".*_callback$" \
235
  --exclude tests \
236
  --exclude docs \
237
  --exclude migrations \
238
  --generate-badge docs/coverage.svg \
239
  --badge-style flat-square \
240
  --verbose \
241
  --color \
242
  src/
243
```
244

245
### Integration Examples
246

247
#### GitHub Actions
248

249
```yaml
250
# .github/workflows/docs.yml
251
- name: Check docstring coverage
252
  run: |
253
    interrogate --fail-under 80 --generate-badge docs/coverage.svg src/
254
    
255
- name: Commit badge
256
  run: |
257
    git add docs/coverage.svg
258
    git commit -m "Update coverage badge" || exit 0
259
    git push
260
```
261

262
#### Pre-commit Hook
263

264
```yaml
265
# .pre-commit-config.yaml
266
- repo: https://github.com/econchick/interrogate
267
  rev: 1.7.0
268
  hooks:
269
    - id: interrogate
270
      args: [--fail-under=80, --ignore-init-method, --ignore-private]
271
```
272

273
#### Makefile Integration
274

275
```makefile
276
# Makefile
277
.PHONY: docs-coverage
278
docs-coverage:
279
	interrogate --generate-badge docs/coverage.svg --fail-under 85 src/
280

281
.PHONY: check-docs
282
check-docs:
283
	interrogate --fail-under 85 --quiet --omit-covered-files src/
284
```
285

286
### Exit Codes
287

288
The CLI returns different exit codes based on analysis results:
289

290
- **0**: Success (coverage meets threshold or no threshold set)
291
- **1**: Coverage below threshold (when `--fail-under` is used)
292
- **2**: Command-line argument error
293
- **3**: Configuration file error
294

295
```bash
296
# Example usage with exit code handling
297
if interrogate --fail-under 80 src/; then
298
    echo "Coverage check passed"
299
else
300
    echo "Coverage check failed"
301
    exit 1
302
fi
303
```
304

305
### Module Execution
306

307
Interrogate can also be run as a Python module:
308

309
```bash
310
# Equivalent to 'interrogate' command
311
python -m interrogate src/
312

313
# With arguments
314
python -m interrogate --fail-under 80 --verbose src/
315
```
316

317
### Help and Version
318

319
```bash
320
# Show help
321
interrogate --help
322

323
# Show version
324
interrogate --version
325
```