0
# Command Line Interface
1

2
The type-coverage CLI provides comprehensive options for measuring and reporting TypeScript type coverage in projects. It analyzes TypeScript code to calculate the percentage of identifiers with explicit types versus 'any' types.
3

4
## Capabilities
5

6
### Basic Type Coverage Analysis
7

8
Check type coverage for a TypeScript project.
9

10
```bash { .api }
11
type-coverage [options] [-- file1.ts file2.ts ...]
12
```
13

14
**Usage Examples:**
15

16
```bash
17
# Basic coverage check
18
type-coverage
19

20
# Check specific project
21
type-coverage -p ./tsconfig.json
22

23
# Check only specific files
24
type-coverage -- src/main.ts src/utils.ts
25
```
26

27
### Project Configuration
28

29
Specify the TypeScript project configuration.
30

31
```bash { .api }
32
-p, --project <string>     Path to tsconfig.json directory or file
33
```
34

35
**Usage Examples:**
36

37
```bash
38
# Use specific tsconfig.json
39
type-coverage -p ./src/tsconfig.json
40

41
# Use tsconfig.json in specific directory
42
type-coverage -p ./backend
43
```
44

45
### Coverage Thresholds
46

47
Set minimum coverage requirements and fail if not met.
48

49
```bash { .api }
50
--at-least <number>        Fail if coverage rate < this value
51
--is <number>              Fail if coverage rate !== this exact value
52
```
53

54
**Usage Examples:**
55

56
```bash
57
# Require at least 90% coverage
58
type-coverage --at-least 90
59

60
# Require exactly 95% coverage
61
type-coverage --is 95
62
```
63

64
### Detailed Reporting
65

66
Control the level of detail in coverage reports.
67

68
```bash { .api }
69
--detail                   Show detailed results with file locations
70
--no-detail-when-failed    Hide details when coverage check fails
71
--show-relative-path       Show relative paths instead of absolute paths
72
--json-output              Output results as JSON format
73
```
74

75
**Usage Examples:**
76

77
```bash
78
# Show detailed results
79
type-coverage --detail --at-least 80
80

81
# JSON output for CI integration
82
type-coverage --json-output --at-least 90
83
```
84

85
### Strict Mode Options
86

87
Enable strict checking modes for higher type safety standards.
88

89
```bash { .api }
90
--strict                   Enable strict mode (includes all strict options)
91
--ignore-catch             Ignore catch clause variables
92
--ignore-nested            Ignore any in type arguments (Promise<any>)
93
--ignore-as-assertion      Ignore as assertions (foo as string)
94
--ignore-type-assertion    Ignore type assertions (<string>foo)
95
--ignore-non-null-assertion Ignore non-null assertions (foo!)
96
--ignore-object            Don't count Object type as any
97
--ignore-empty-type        Don't count empty type {} as any
98
--ignore-unread            Allow writes to variables with implicit any types
99
```
100

101
**Usage Examples:**
102

103
```bash
104
# Enable all strict checks
105
type-coverage --strict --at-least 95
106

107
# Custom strict configuration
108
type-coverage --ignore-catch --ignore-nested --at-least 90
109
```
110

111
### File Filtering
112

113
Control which files are included in the analysis.
114

115
```bash { .api }
116
--ignore-files <patterns>  Ignore files matching glob patterns (can be repeated)
117
--not-only-in-cwd         Include results outside current working directory
118
-- <files>                Only check specified files
119
```
120

121
**Usage Examples:**
122

123
```bash
124
# Ignore test files and generated code
125
type-coverage --ignore-files "**/*.test.ts" --ignore-files "**/generated/**"
126

127
# Check only specific files (useful with lint-staged)
128
type-coverage -- src/main.ts src/utils.ts
129

130
# Include files outside current directory
131
type-coverage --not-only-in-cwd
132
```
133

134
### Performance and Caching
135

136
Enable caching for improved performance on large codebases.
137

138
```bash { .api }
139
--cache                    Enable result caching
140
--cache-directory <path>   Set custom cache directory location
141
```
142

143
**Usage Examples:**
144

145
```bash
146
# Enable caching (uses .type-coverage directory)
147
type-coverage --cache --at-least 90
148

149
# Use custom cache directory
150
type-coverage --cache --cache-directory ./build/.type-coverage
151
```
152

153
### Configuration Management
154

155
Update package.json configuration based on results.
156

157
```bash { .api }
158
--update                   Update typeCoverage section in package.json
159
--update-if-higher         Update only if new coverage is higher
160
```
161

162
**Usage Examples:**
163

164
```bash
165
# Update package.json with current coverage
166
type-coverage --update
167

168
# Update only if coverage improved
169
type-coverage --update-if-higher
170
```
171

172
### History and Tracking
173

174
Track coverage changes over time.
175

176
```bash { .api }
177
--history-file <filename>  Save coverage history to specified file
178
```
179

180
**Usage Examples:**
181

182
```bash
183
# Track coverage over time
184
type-coverage --history-file coverage-history.json --at-least 85
185
```
186

187
### Error Reporting
188

189
Include additional error reporting and diagnostics.
190

191
```bash { .api }
192
--report-semantic-error    Report TypeScript semantic errors
193
--report-unused-ignore     Report unused type-coverage ignore directives
194
--debug                    Show debug information during analysis
195
```
196

197
**Usage Examples:**
198

199
```bash
200
# Include semantic errors in analysis
201
type-coverage --report-semantic-error --detail
202

203
# Show debug information
204
type-coverage --debug --detail
205
```
206

207
### Help and Version
208

209
Display help information and version details.
210

211
```bash { .api }
212
-h, --help                 Show help information
213
-v, --version              Show version number
214
```
215

216
**Usage Examples:**
217

218
```bash
219
# Show help
220
type-coverage --help
221

222
# Show version
223
type-coverage --version
224
```
225

226
## Package.json Configuration
227

228
Type coverage can be configured via package.json to avoid repeating CLI arguments:
229

230
```json { .api }
231
{
232
  "typeCoverage": {
233
    "atLeast": 90,
234
    "detail": true,
235
    "strict": true,
236
    "ignoreCatch": true,
237
    "ignoreFiles": ["**/*.test.ts", "**/generated/**"],
238
    "ignoreUnread": false,
239
    "showRelativePath": true,
240
    "cache": true
241
  }
242
}
243
```
244

245
CLI arguments override package.json configuration when both are present.
246

247
## Exit Codes
248

249
```bash { .api }
250
0    Success - coverage meets requirements
251
1    Failure - coverage below threshold or errors occurred
252
```
253

254
## Integration Examples
255

256
### CI/CD Integration
257

258
```bash
259
# GitHub Actions / Jenkins
260
type-coverage --at-least 90 --no-detail-when-failed
261

262
# Generate coverage report for artifacts
263
type-coverage --json-output --detail > coverage-report.json
264
```
265

266
### Pre-commit Hooks
267

268
```bash
269
# With lint-staged - check only staged files
270
type-coverage -- $(git diff --cached --name-only --diff-filter=AM | grep '\\.ts$')
271
```
272

273
### Progressive Migration
274

275
```bash
276
# Start with low threshold and gradually increase
277
type-coverage --at-least 70 --update-if-higher --history-file coverage-history.json
278
```