0
# Command Line Interface
1

2
The npm-check CLI provides an interactive and automated interface for analyzing and updating npm dependencies. It supports both local project analysis and global package management.
3

4
## Capabilities
5

6
### Basic Command
7

8
The primary command-line interface for npm-check.
9

10
```bash { .api }
11
npm-check [path] [options]
12

13
# Basic usage
14
npm-check                    # Analyze current directory
15
npm-check ./my-project       # Analyze specific directory
16
npm-check /path/to/project   # Analyze absolute path
17
```
18

19
**Usage Examples:**
20

21
```bash
22
# Check current directory for outdated and unused packages
23
npm-check
24

25
# Check a specific project directory
26
npm-check ./my-react-app
27

28
# Check with verbose output for debugging
29
npm-check --debug
30
```
31

32
### Interactive Update Mode
33

34
Provides an interactive interface for selectively updating packages.
35

36
```bash { .api }
37
-u, --update                 # Interactive update mode
38
```
39

40
**Usage Examples:**
41

42
```bash
43
# Interactive update of local packages
44
npm-check -u
45

46
# Interactive update of global packages  
47
npm-check -g -u
48

49
# Interactive update with exact versions
50
npm-check -u -E
51
```
52

53
Features of interactive mode:
54
- Navigate with arrow keys to select packages
55
- Space bar to toggle package selection
56
- Shows changelog links for informed decisions
57
- Respects semver and package-lock.json constraints
58
- Uses locally installed npm version for updates
59

60
### Automated Update Mode
61

62
Updates all outdated packages without user interaction.
63

64
```bash { .api }
65
-y, --update-all             # Update all packages without prompting
66
```
67

68
**Usage Examples:**
69

70
```bash
71
# Update all local packages automatically
72
npm-check -y
73

74
# Update all global packages automatically  
75
npm-check -g -y
76

77
# Update all with exact versions
78
npm-check -y -E
79
```
80

81
### Scope Options
82

83
Control which types of dependencies to analyze and update.
84

85
```bash { .api }
86
-g, --global                 # Check global modules
87
-p, --production             # Skip devDependencies  
88
-d, --dev-only               # Only check devDependencies
89
-s, --skip-unused            # Skip unused package detection
90
```
91

92
**Usage Examples:**
93

94
```bash
95
# Check only globally installed packages
96
npm-check -g
97

98
# Check only production dependencies (ignore devDependencies)
99
npm-check -p
100

101
# Check only development dependencies (ignore dependencies)  
102
npm-check -d
103

104
# Skip the unused package analysis (faster execution)
105
npm-check -s
106

107
# Combined: interactive update of global packages, skip unused check
108
npm-check -g -u -s
109
```
110

111
### Filtering Options
112

113
Control which packages to include or exclude from analysis.
114

115
```bash { .api }
116
-i, --ignore <glob>          # Ignore dependencies matching glob pattern
117
--specials <list>            # Include specific depcheck specials
118
```
119

120
**Usage Examples:**
121

122
```bash
123
# Ignore all babel-related packages
124
npm-check -i "babel-*"
125

126
# Ignore multiple patterns (use quotes for complex patterns)
127
npm-check -i "@types/*,eslint-*"
128

129
# Include webpack config in unused package detection
130
npm-check --specials=webpack
131

132
# Include multiple specials
133
npm-check --specials=bin,webpack,babel
134
```
135

136
### Installation Options
137

138
Control how packages are installed when updating.
139

140
```bash { .api }
141
-E, --save-exact             # Save exact versions instead of semver ranges
142
```
143

144
**Usage Examples:**
145

146
```bash
147
# Update with exact versions (no ^ or ~ prefixes)
148
npm-check -u -E
149

150
# Automated update with exact versions
151
npm-check -y -E
152
```
153

154
### Output Options
155

156
Control the appearance and verbosity of output.
157

158
```bash { .api }
159
--no-color                   # Disable colored output
160
--no-emoji                   # Disable emoji in output
161
--no-spinner                 # Disable loading spinners
162
--debug                      # Enable debug output
163
```
164

165
**Usage Examples:**
166

167
```bash
168
# Plain text output without colors or emoji (good for CI)
169
npm-check --no-color --no-emoji
170

171
# Debug mode with detailed output
172
npm-check --debug
173

174
# Quiet mode without spinners (good for scripting)
175
npm-check --no-spinner
176
```
177

178
### Environment Variables
179

180
Configure npm-check behavior through environment variables.
181

182
```bash { .api }
183
# Set preferred package manager
184
export NPM_CHECK_INSTALLER=pnpm
185
export NPM_CHECK_INSTALLER=yarn
186
export NPM_CHECK_INSTALLER=npm
187

188
# Override global node_modules path
189
export NODE_PATH=/custom/path/to/node_modules
190
```
191

192
**Usage Examples:**
193

194
```bash
195
# Use pnpm for updates
196
NPM_CHECK_INSTALLER=pnpm npm-check -u
197

198
# Use yarn for updates
199
NPM_CHECK_INSTALLER=yarn npm-check -u
200

201
# Dry run using echo (for testing)
202
NPM_CHECK_INSTALLER=echo npm-check -u
203

204
# Custom global modules path
205
NODE_PATH=/usr/local/lib/node_modules npm-check -g
206
```
207

208
### Configuration File Support
209

210
npm-check supports configuration files for advanced depcheck options.
211

212
```bash { .api }
213
# Configuration files (in order of precedence):
214
.npmcheckrc
215
.npmcheckrc.json
216
.npmcheckrc.yml
217
.npmcheckrc.js
218
```
219

220
**Configuration Example:**
221

222
```yaml
223
# .npmcheckrc
224
depcheck:
225
  ignoreMatches: 
226
    - "replace-in-file"
227
    - "snyk"
228
    - "sonarqube-scanner"
229
  ignoreDirs:
230
    - "build"
231
    - "dist"
232
  specials:
233
    - "webpack"
234
    - "babel"
235
```
236

237
### Exit Codes
238

239
npm-check returns different exit codes based on analysis results.
240

241
```bash { .api }
242
# Exit codes:
243
0    # All packages are up to date and in use
244
1    # Outdated packages or unused packages found  
245
1    # Error occurred during analysis
246
```
247

248
**Usage Examples:**
249

250
```bash
251
# Use in CI/CD pipelines
252
npm-check
253
if [ $? -ne 0 ]; then
254
  echo "Dependencies need attention"
255
  exit 1
256
fi
257

258
# Combined with other commands
259
npm-check && npm test && npm run build
260
```
261

262
### Common Workflows
263

264
Typical usage patterns for different scenarios.
265

266
**Development Workflow:**
267
```bash
268
# Daily dependency check
269
npm-check
270

271
# Weekly interactive update
272
npm-check -u
273

274
# Pre-commit check (skip unused for speed)
275
npm-check -s
276
```
277

278
**CI/CD Pipeline:**
279
```bash
280
# Check for outdated dependencies (fail build if found)
281
npm-check --no-color --no-emoji
282

283
# Production-only check
284
npm-check -p --no-color
285
```
286

287
**Global Package Management:**
288
```bash
289
# Check global packages
290
npm-check -g
291

292
# Update global packages interactively
293
npm-check -g -u
294

295
# Update all global packages including npm itself
296
npm-check -g -y
297
```
298

299
**Project Maintenance:**
300
```bash
301
# Find unused dependencies
302
npm-check
303

304
# Clean update with exact versions
305
npm-check -u -E
306

307
# Debug dependency issues
308
npm-check --debug
309
```