0
# CLI Interface
1

2
Command-line interface providing access to all npm-check-updates functionality through terminal commands. Supports comprehensive configuration options for dependency management.
3

4
## Capabilities
5

6
### Basic Commands
7

8
Primary command-line interface with multiple binary names.
9

10
```bash { .api }
11
# Full command name
12
npm-check-updates [options] [filter...]
13

14
# Short alias
15
ncu [options] [filter...]
16
```
17

18
**Usage Examples:**
19

20
```bash
21
# Check for updates
22
ncu
23

24
# Upgrade package.json
25
ncu -u
26

27
# Check specific packages
28
ncu express lodash
29

30
# Use filter patterns
31
ncu "react*" "@types/*"
32
```
33

34
### Core Options
35

36
Essential options for basic upgrade operations.
37

38
```bash { .api }
39
--upgrade, -u                    # Overwrite package file with upgraded versions
40
--interactive, -i                # Enable interactive prompts for each dependency
41
--global, -g                     # Check global packages instead of local project
42
--packageFile <file>             # Package file location (default: ./package.json)
43
--packageManager <manager>       # npm, yarn, pnpm, deno, bun, staticRegistry
44
```
45

46
**Usage Examples:**
47

48
```bash
49
# Upgrade package.json
50
ncu --upgrade
51

52
# Interactive selection
53
ncu --interactive
54

55
# Global packages
56
ncu --global
57

58
# Specific package file
59
ncu --packageFile ./packages/core/package.json
60

61
# Use yarn
62
ncu --packageManager yarn
63
```
64

65
### Version Targeting
66

67
Control which versions to upgrade to.
68

69
```bash { .api }
70
--target <target>                # latest, newest, greatest, minor, patch, semver, @tag
71
--peer                          # Check peer dependencies
72
--dep <dep>                     # Check specific dependency sections (prod, dev, optional, peer)
73
```
74

75
**Usage Examples:**
76

77
```bash
78
# Only minor updates
79
ncu --target minor
80

81
# Only patch updates  
82
ncu --target patch
83

84
# Specific npm tag
85
ncu --target @beta
86

87
# Only production dependencies
88
ncu --dep prod
89

90
# Multiple dependency types
91
ncu --dep prod,dev
92
```
93

94
### Filtering Options
95

96
Control which packages to check and upgrade.
97

98
```bash { .api }
99
--filter <pattern>               # Include only package names matching pattern
100
--reject <pattern>               # Exclude package names matching pattern
101
--filterVersion <pattern>        # Include only versions matching pattern
102
```
103

104
**Usage Examples:**
105

106
```bash
107
# Include only React packages
108
ncu --filter "react*"
109

110
# Exclude dev tools
111
ncu --reject "eslint*,prettier"
112

113
# Complex regex pattern
114
ncu --filter "/^@myorg\//"
115

116
# Filter by version pattern
117
ncu --filterVersion "/^1\./"
118
```
119

120
### Output Formatting
121

122
Control the display and format of upgrade information.
123

124
```bash { .api }
125
--format <format>                # table, group, ownerChanged, repo, time, lines
126
--color, --no-color              # Enable/disable colored output
127
--loglevel <level>               # silent, error, minimal, warn, info, verbose, silly
128
--json                          # Output upgrades as json
129
--jsonUpgraded                  # Output only upgraded dependencies as json
130
```
131

132
**Usage Examples:**
133

134
```bash
135
# Grouped output
136
ncu --format group
137

138
# No colors
139
ncu --no-color
140

141
# JSON output
142
ncu --json
143

144
# Only upgraded packages as JSON
145
ncu --jsonUpgraded
146

147
# Verbose logging
148
ncu --loglevel verbose
149
```
150

151
### Advanced Features
152

153
Specialized functionality for complex upgrade scenarios.
154

155
```bash { .api }
156
--doctor                        # Iteratively install upgrades and run tests
157
--deep                         # Run recursively in current working directory
158
--workspaces                   # Check all workspaces
159
--workspace <workspace>        # Check specific workspace(s)
160
--timeout <ms>                 # Global timeout in milliseconds
161
```
162

163
**Usage Examples:**
164

165
```bash
166
# Doctor mode - test after each upgrade
167
ncu --doctor --upgrade
168

169
# Check all subdirectories
170
ncu --deep
171

172
# All workspaces
173
ncu --workspaces
174

175
# Specific workspace
176
ncu --workspace packages/core
177

178
# 30 second timeout
179
ncu --timeout 30000
180
```
181

182
### Caching Options
183

184
Manage version caching for improved performance.
185

186
```bash { .api }
187
--cache                         # Cache versions to local cache file
188
--cacheFile <file>             # Filepath for cache file
189
--cacheClear                   # Clear cache before running
190
```
191

192
**Usage Examples:**
193

194
```bash
195
# Enable caching
196
ncu --cache
197

198
# Custom cache file
199
ncu --cacheFile ~/.ncu-cache-custom.json
200

201
# Clear cache first
202
ncu --cacheClear
203
```
204

205
### Installation Options
206

207
Control automatic installation after upgrading.
208

209
```bash { .api }
210
--install <mode>               # always, never, prompt
211
```
212

213
**Usage Examples:**
214

215
```bash
216
# Always install after upgrade
217
ncu --upgrade --install always
218

219
# Never prompt for install
220
ncu --upgrade --install never
221

222
# Prompt in interactive mode
223
ncu --interactive --install prompt
224
```
225

226
### Registry and Authentication
227

228
Configure package registry and authentication.
229

230
```bash { .api }
231
--registry <url>               # Third-party npm registry
232
--registryType <type>         # npm, yarn, pnpm
233
```
234

235
**Usage Examples:**
236

237
```bash
238
# Private registry
239
ncu --registry https://npm.company.com
240

241
# Use yarn registry config
242
ncu --registryType yarn
243
```
244

245
### Error Handling
246

247
Control error reporting and exit codes.
248

249
```bash { .api }
250
--errorLevel <level>           # 1: exit with error on uncaught errors
251
                              # 2: exit with error if any packages can be upgraded
252
--retry <count>               # Number of times to retry failed network requests
253
```
254

255
**Usage Examples:**
256

257
```bash
258
# Exit with error if upgrades available
259
ncu --errorLevel 2
260

261
# Retry failed requests
262
ncu --retry 3
263
```
264

265
### Help and Information
266

267
Get help and version information.
268

269
```bash { .api }
270
--help, -h                     # Display help
271
--version, -V                  # Output version number
272
```
273

274
**Usage Examples:**
275

276
```bash
277
# Show help
278
ncu --help
279

280
# Show version
281
ncu --version
282
```
283

284
### Configuration Files
285

286
Support for configuration files to avoid repeating options.
287

288
```bash { .api }
289
# Configuration file support (.ncurc.js, .ncurc.json, .ncurc.yml)
290
--configFileName <filename>    # Config file name (default: .ncurc)
291
--configFilePath <path>       # Config file path
292
--mergeConfig                 # Merge config with CLI options
293
```
294

295
**Usage Examples:**
296

297
```bash
298
# Use custom config file
299
ncu --configFileName myconfig
300

301
# Specific config path
302
ncu --configFilePath /path/to/config.json
303

304
# Merge config with CLI options
305
ncu --mergeConfig --target minor
306
```