0
# CLI Usage
1

2
Comprehensive command-line interface with extensive options for analysis, fixing, and workflow integration. The CLI provides access to all Knip functionality with detailed configuration options.
3

4
## Capabilities
5

6
### Basic Commands
7

8
Core CLI commands for different analysis modes.
9

10
```bash { .api }
11
# Basic analysis of current project
12
knip
13

14
# Analyze with specific configuration file  
15
knip --config knip.json
16
knip -c knip.config.js
17

18
# Analyze with TypeScript configuration
19
knip --tsConfig tsconfig.json
20
knip -t tsconfig.build.json
21

22
# Production analysis only (no test files, devDependencies)
23
knip --production
24

25
# Strict mode (only direct dependencies)
26
knip --strict
27

28
# Analyze single workspace
29
knip --workspace packages/frontend
30
knip -W packages/backend
31

32
# Run from different directory
33
knip --directory /path/to/project
34

35
# Show help
36
knip --help
37
knip -h
38

39
# Show version
40
knip --version
41
knip -V
42
```
43

44
### Analysis Options
45

46
Control what gets analyzed and how.
47

48
```bash { .api }
49
# Enable caching for faster repeated runs
50
knip --cache
51

52
# Specify cache location
53
knip --cache-location node_modules/.cache/knip-custom
54

55
# Watch mode for continuous analysis
56
knip --watch
57

58
# Don't use .gitignore files
59
knip --no-gitignore
60

61
# Include type definitions from external dependencies
62
knip --include-libs
63

64
# Include entry exports in unused exports report
65
knip --include-entry-exports
66

67
# Isolate workspaces into separate programs
68
knip --isolate-workspaces
69
```
70

71
### Issue Type Filtering
72

73
Control which types of issues are reported.
74

75
```bash { .api }
76
# Include only specific issue types (can be repeated)
77
knip --include dependencies
78
knip --include dependencies,exports,files
79
knip --include dependencies --include exports
80

81
# Exclude specific issue types (can be repeated)  
82
knip --exclude types
83
knip --exclude types,classMembers
84
knip --exclude types --exclude classMembers
85

86
# Shortcut for dependency-related issues
87
knip --dependencies
88
# Equivalent to: --include dependencies,unlisted,binaries,unresolved
89

90
# Shortcut for export-related issues
91
knip --exports  
92
# Equivalent to: --include exports,nsExports,classMembers,types,nsTypes,enumMembers,duplicates
93

94
# Shortcut for unused files only
95
knip --files
96
# Equivalent to: --include files
97
```
98

99
**Available Issue Types:**
100

101
- `files` - Unused files
102
- `dependencies` - Unused dependencies
103
- `devDependencies` - Unused devDependencies
104
- `optionalPeerDependencies` - Referenced optional peerDependencies
105
- `unlisted` - Unlisted dependencies
106
- `binaries` - Unlisted binaries
107
- `unresolved` - Unresolved imports
108
- `exports` - Unused exports
109
- `nsExports` - Exports in used namespace
110
- `types` - Unused exported types
111
- `nsTypes` - Exported types in used namespace
112
- `enumMembers` - Unused exported enum members
113
- `classMembers` - Unused exported class members
114
- `duplicates` - Duplicate exports
115

116
### Fixing Options
117

118
Automatically fix detected issues.
119

120
```bash { .api }
121
# Fix all fixable issues
122
knip --fix
123

124
# Fix only specific issue types
125
knip --fix-type exports
126
knip --fix-type dependencies,exports
127
knip --fix-type exports --fix-type types
128

129
# Allow Knip to remove files (dangerous!)
130
knip --allow-remove-files
131

132
# Format files after fixing
133
knip --format
134
```
135

136
**Fixable Issue Types:**
137

138
- Unused imports and exports
139
- Unused variable declarations  
140
- Unused dependencies in package.json
141
- Some unused files (with `--allow-remove-files`)
142

143
### Output and Reporting
144

145
Control output format and verbosity.
146

147
```bash { .api }
148
# Select reporter (can be repeated for multiple outputs)
149
knip --reporter symbols        # Default terminal output
150
knip --reporter compact        # Compact terminal output
151
knip --reporter json          # JSON format
152
knip --reporter markdown      # Markdown format
153
knip --reporter codeowners    # GitHub CODEOWNERS format
154
knip --reporter codeclimate   # Code Climate format
155
knip --reporter disclosure    # Issue summary
156

157
# Multiple reporters
158
knip --reporter json --reporter markdown
159

160
# Pass options to reporters (JSON format)
161
knip --reporter json --reporter-options '{"indent":2,"sort":true}'
162

163
# Don't show dynamic progress updates
164
knip --no-progress
165
knip -n
166

167
# Suppress configuration hints
168
knip --no-config-hints
169

170
# Treat configuration hints as errors (exit code 1)
171
knip --treat-config-hints-as-errors
172
```
173

174
### Preprocessing
175

176
Transform results before reporting.
177

178
```bash { .api }
179
# Apply preprocessors (can be repeated)
180
knip --preprocessor sort
181
knip --preprocessor filter --preprocessor sort
182

183
# Pass options to preprocessors (JSON format)
184
knip --preprocessor-options '{"filter":{"minSeverity":"error"}}'
185
```
186

187
### Tag Filtering
188

189
Filter exports based on JSDoc-style tags.
190

191
```bash { .api }
192
# Include or exclude tagged exports
193
knip --tags
194

195
# Legacy flag (deprecated, use --tags)
196
knip --experimental-tags
197
```
198

199
**Supported Tags:**
200

201
- `@public` - Mark as public API
202
- `@internal` - Mark as internal/private
203
- `@beta` - Mark as beta/experimental
204
- `@alias` - Mark as alias
205

206
### Exit Codes and Error Handling
207

208
Control CLI exit behavior.
209

210
```bash { .api }
211
# Always exit with code 0 (success)
212
knip --no-exit-code
213

214
# Set maximum issues before error exit (default: 0)
215
knip --max-issues 10
216
```
217

218
**Exit Codes:**
219

220
- `0` - Success (no issues or `--no-exit-code`)
221
- `1` - Issues found exceeding `--max-issues` threshold
222
- `2` - Runtime error or configuration problem
223

224
### Debug and Performance
225

226
Debugging and performance analysis options.
227

228
```bash { .api }
229
# Show debug output
230
knip --debug
231
knip -d
232

233
# Show trace output for analysis
234
knip --trace
235

236
# Trace specific exports
237
knip --trace-export MyFunction
238
knip --trace-export MyClass,MyInterface
239

240
# Trace exports in specific file
241
knip --trace-file src/api.ts
242

243
# Performance measurement
244
knip --performance
245

246
# Measure specific function performance
247
knip --performance-fn analyzeSourceFile
248

249
# Memory usage tracking
250
knip --memory
251

252
# Real-time memory usage logging
253
knip --memory-realtime
254
```
255

256
### Configuration Examples
257

258
Common CLI usage patterns.
259

260
```bash { .api }
261
# Development workflow
262
knip --watch --reporter compact
263

264
# CI/CD pipeline
265
knip --production --reporter json --no-progress --max-issues 0
266

267
# Pre-commit hook  
268
knip --include exports,types --fix --format
269

270
# Code review
271
knip --reporter markdown > knip-report.md
272

273
# Dependency audit
274
knip --dependencies --reporter json
275

276
# Export cleanup
277
knip --exports --fix --no-exit-code
278

279
# Performance analysis
280
knip --performance --memory --debug
281

282
# Monorepo analysis
283
knip --workspace packages/frontend --production
284
knip --isolate-workspaces --reporter json
285
```
286

287
### Environment Variables
288

289
Environment variables that affect CLI behavior.
290

291
```bash { .api }
292
# Disable progress in CI environments (automatic)
293
CI=true knip
294

295
# Custom cache location
296
KNIP_CACHE_LOCATION=/tmp/knip-cache knip --cache
297

298
# Node environment affects plugin behavior
299
NODE_ENV=production knip
300
```
301

302
### Integration Examples
303

304
**Package.json Scripts:**
305

306
```json
307
{
308
  "scripts": {
309
    "knip": "knip",
310
    "knip:prod": "knip --production --strict",
311
    "knip:fix": "knip --fix --format",
312
    "knip:ci": "knip --reporter json --no-progress"
313
  }
314
}
315
```
316

317
**GitHub Actions:**
318

319
```yaml
320
- name: Run Knip
321
  run: |
322
    npm run knip:ci > knip-results.json
323
    if [ -s knip-results.json ]; then
324
      echo "Issues found:"
325
      cat knip-results.json
326
      exit 1
327
    fi
328
```
329

330
**Pre-commit Hook:**
331

332
```bash
333
#!/bin/sh
334
# .git/hooks/pre-commit
335
npx knip --include exports --fix --format --no-exit-code
336
git add -u
337
```
338

339
**Watch Script:**
340

341
```bash
342
#!/bin/bash
343
# watch-knip.sh
344
npx knip --watch --reporter compact --no-progress
345
```
346

347
### CLI Arguments Interface
348

349
TypeScript interface for CLI arguments (for tool integration).
350

351
```typescript { .api }
352
interface CLIArguments {
353
  /** Configuration file path */
354
  config?: string;
355
  /** TypeScript configuration path */
356
  tsConfig?: string;
357
  /** Production mode */
358
  production?: boolean;
359
  /** Strict mode */
360
  strict?: boolean;
361
  /** Single workspace analysis */
362
  workspace?: string;
363
  /** Working directory */
364
  directory?: string;
365
  /** Enable caching */
366
  cache?: boolean;
367
  /** Cache location */
368
  'cache-location'?: string;
369
  /** Watch mode */
370
  watch?: boolean;
371
  /** Don't use .gitignore */
372
  'no-gitignore'?: boolean;
373
  /** Issue types to include */
374
  include?: string | string[];
375
  /** Issue types to exclude */
376
  exclude?: string | string[];
377
  /** Dependency shortcut */
378
  dependencies?: boolean;
379
  /** Exports shortcut */
380
  exports?: boolean;
381
  /** Files shortcut */
382
  files?: boolean;
383
  /** Fix issues */
384
  fix?: boolean;
385
  /** Fix specific types */
386
  'fix-type'?: string | string[];
387
  /** Allow file removal */
388
  'allow-remove-files'?: boolean;
389
  /** Format after fixing */
390
  format?: boolean;
391
  /** Include external libs */
392
  'include-libs'?: boolean;
393
  /** Include entry exports */
394
  'include-entry-exports'?: boolean;
395
  /** Isolate workspaces */
396
  'isolate-workspaces'?: boolean;
397
  /** Don't show progress */
398
  'no-progress'?: boolean;
399
  /** Preprocessor */
400
  preprocessor?: string | string[];
401
  /** Preprocessor options */
402
  'preprocessor-options'?: string;
403
  /** Reporter */
404
  reporter?: string | string[];
405
  /** Reporter options */
406
  'reporter-options'?: string;
407
  /** Tag filtering */
408
  tags?: string | string[];
409
  /** Disable config hints */
410
  'no-config-hints'?: boolean;
411
  /** Config hints as errors */
412
  'treat-config-hints-as-errors'?: boolean;
413
  /** Always exit 0 */
414
  'no-exit-code'?: boolean;
415
  /** Maximum issues */
416
  'max-issues'?: number;
417
  /** Debug output */
418
  debug?: boolean;
419
  /** Trace output */
420
  trace?: boolean;
421
  /** Trace export */
422
  'trace-export'?: string | string[];
423
  /** Trace file */
424
  'trace-file'?: string | string[];
425
  /** Performance measurement */
426
  performance?: boolean;
427
  /** Performance function */
428
  'performance-fn'?: string | string[];
429
  /** Memory usage */
430
  memory?: boolean;
431
  /** Real-time memory */
432
  'memory-realtime'?: boolean;
433
  /** Show help */
434
  help?: boolean;
435
  /** Show version */
436
  version?: boolean;
437
}
438
```