Skip to content
Newer
Older
100644 310 lines (188 sloc) 7.91 KB
f85134f @isaacs refactor config doc
isaacs authored
1 npm-config(1) -- Manage the npm configuration file
2 ==================================================
3
64afd3d @isaacs Clean up the docs further. Make them more consistent.
isaacs authored
4 ## SYNOPSIS
5
780c9ae @isaacs Update docs with changed/corrected information
isaacs authored
6 npm config set <key> <value> [--global]
64afd3d @isaacs Clean up the docs further. Make them more consistent.
isaacs authored
7 npm config get <key>
8 npm config delete <key>
9 npm config list
8a5eaa6 @isaacs document config edit
isaacs authored
10 npm config edit
64afd3d @isaacs Clean up the docs further. Make them more consistent.
isaacs authored
11
12 ## DESCRIPTION
13
780c9ae @isaacs Update docs with changed/corrected information
isaacs authored
14 npm gets its configuration values from 5 sources, in this priority:
15
16 * cli:
17 The command line flags. Putting `--foo bar` on the command line sets the
18 `foo` configuration parameter to `"bar"`. A `--` argument tells the cli
19 parser to stop reading flags. A `--flag` parameter that is at the *end* of
20 the command will be given the value of `true`.
21 * env:
22 Any environment variables that start with `npm_config_` will be interpreted
23 as a configuration parameter. For example, putting `npm_config_foo=bar` in
24 your environment will set the `foo` configuration parameter to `bar`. Any
25 environment configurations that are not given a value will be given the value
26 of `true`. Config values are case-insensitive, so `NPM_CONFIG_FOO=bar` will
27 work the same.
28 * $HOME/.npmrc (or the `userconfig` param, if set above):
29 This file is an ini-file formatted list of `key = value` parameters.
30 * $PREFIX/etc/npmrc (or the `globalconfig` param, if set above):
31 This file is an ini-file formatted list of `key = value` parameters
32 * default configs:
33 This is a set of configuration parameters that are internal to npm, and are
34 defaults if nothing else is specified.
f85134f @isaacs refactor config doc
isaacs authored
35
36 ## Sub-commands
37
38 Config supports the following sub-commands:
39
40 ### set
41
42 npm config set key value
43
44 Sets the config key to the value.
45
46 ### get
47
48 npm config get key
49
50 Echo the config value to stdout. (NOTE: All the other npm logging is done to
51 stderr, so pipes should work properly, and you can do `npm get key 2>/dev/null`
52 to print out JUST the config value.)
53
54 ### list
55
56 npm config list
57
58 Show all the config settings.
59
64afd3d @isaacs Clean up the docs further. Make them more consistent.
isaacs authored
60 ### delete
f85134f @isaacs refactor config doc
isaacs authored
61
62 npm config delete key
63
780c9ae @isaacs Update docs with changed/corrected information
isaacs authored
64 Deletes the key from all configuration files.
f85134f @isaacs refactor config doc
isaacs authored
65
8a5eaa6 @isaacs document config edit
isaacs authored
66 ### edit
67
68 npm config edit
69
70 Opens the config file in an editor. Use the `--global` flag to edit the global config.
71
57729b7 @isaacs Documentation updates
isaacs authored
72 ## Config Settings
73
74 npm supports a very basic argument parser. For any of the settings
75 in npm-config(1), you can set them explicitly for a single command by
76 doing:
77
78 npm --key val <command>
79
80 Configurations defined on the command line are not saved to the .npmrc file.
f85134f @isaacs refactor config doc
isaacs authored
81
c24e212 @isaacs Document new config values
isaacs authored
82 ### recursive
83
84 Default: false
85
86 Set to some truish value to recursively remove dependent packages. For
87 example if foo depends on bar, and bar depends on baz, then:
88
89 npm uninstall baz --recursive
90
91 will remove baz, bar, and foo.
92
4ff3ddf @isaacs Docs for loglevel conf setting.
isaacs authored
93 ### loglevel
94
95 Default: "info"
96
a4dcfb1 @isaacs Better documnetation of loglevel configs
isaacs authored
97 The log level to show.
98
99 Each level maps to a numeric value, above which all logs must pass to be
100 seen. So, setting it to "warn" shows "win", "error" and "warn" messages.
101
102 The log levels:
103
104 * silent: Show no output. Nothing. If there is output on stderr, it's
105 because something is broken.
106 * win: Show the "npm ok" or "npm not ok", but that's all.
107 * error: Errors, usually with a stack trace.
108 * warn: Things that you should probably be aware of.
109 * info: Helpful info.
110 * silly: Not-helpful info. (Lots of dumping whole objects and such.)
111
112 Note that output to stdout is always printed. This setting just modifies
113 what's logged to stderr.
4ff3ddf @isaacs Docs for loglevel conf setting.
isaacs authored
114
f85134f @isaacs refactor config doc
isaacs authored
115 ### auto-activate
116
117 Default: true
118
119 Automatically activate a package after installation, if there is not an active
120 version already. Set to "always" to always activate when installing.
121
a0eb2fa @isaacs Rename auto-update to update-dependents, and update docs to reflect this
isaacs authored
122 ### update-dependents
123
124 Default: true
125
126 Automatically update a package's dependencies after installation, if it is the
127 newest version installed. Set to "always" to update dependents when a new
128 version is installed, even if it's not the newest.
129
f85134f @isaacs refactor config doc
isaacs authored
130 ### root
131
780c9ae @isaacs Update docs with changed/corrected information
isaacs authored
132 Default: `$INSTALL_PREFIX/lib/node`
f85134f @isaacs refactor config doc
isaacs authored
133
134 The root folder where packages are installed and npm keeps its data.
135
57729b7 @isaacs Documentation updates
isaacs authored
136 ### binroot
137
138 Default: `$INSTALL_PREFIX/bin`
139
140 The folder where executable programs are installed.
141
3ff3ffe @isaacs Document the hidden feature of disabling bins by setting binroot to "…
isaacs authored
142 Set to "false" to not install executables
143
c91d36a @isaacs document "manroot" config
isaacs authored
144 ### manroot
145
146 Default: $INSTALL_PREFIX/share/man
147
148 The folder where man pages are installed.
149
3ff3ffe @isaacs Document the hidden feature of disabling bins by setting binroot to "…
isaacs authored
150 Set to "false" to not install man pages.
151
f85134f @isaacs refactor config doc
isaacs authored
152 ### registry
153
57729b7 @isaacs Documentation updates
isaacs authored
154 Default: https://registry.npmjs.org/
f85134f @isaacs refactor config doc
isaacs authored
155
156 The base URL of the npm package registry.
157
7b2846d @isaacs Update docs for _configName changes
isaacs authored
158 ### _auth
f85134f @isaacs refactor config doc
isaacs authored
159
57729b7 @isaacs Documentation updates
isaacs authored
160 A base-64 encoded "user:pass" pair. This is created by npm-adduser(1).
161
162 If your config file is ever corrupted, you can set this manually by doing:
f85134f @isaacs refactor config doc
isaacs authored
163
7b2846d @isaacs Update docs for _configName changes
isaacs authored
164 npm adduser
57729b7 @isaacs Documentation updates
isaacs authored
165
7b2846d @isaacs Update docs for _configName changes
isaacs authored
166 ### _authCrypt
57729b7 @isaacs Documentation updates
isaacs authored
167
168 If crypto.Cipher is available, and you have some private keys in `$HOME/.ssh`,
7b2846d @isaacs Update docs for _configName changes
isaacs authored
169 then npm will encrypt your "_auth" config before saving to the .npmrc file,
170 and will decrypt the "_authCrypt" config when it reads the .npmrc file.
57729b7 @isaacs Documentation updates
isaacs authored
171
172 ### tag
173
780c9ae @isaacs Update docs with changed/corrected information
isaacs authored
174 Default: latest
57729b7 @isaacs Documentation updates
isaacs authored
175
176 If you ask npm to install a package and don't tell it a specific version, then
177 it will install the specified tag.
f85134f @isaacs refactor config doc
isaacs authored
178
57729b7 @isaacs Documentation updates
isaacs authored
179 Note: this has no effect on the npm-tag(1) command.
c42fe61 @cliffano Add proxy support
cliffano authored
180
181 ### proxy
182
183 If proxy is available, then npm will fetch the modules from the registry via
184 the proxy server.
185
186 Example:
187
188 proxy = http://proxy-server:8080
780c9ae @isaacs Update docs with changed/corrected information
isaacs authored
189
190 ### userconfig
191
192 The default user configuration file is process.env.HOME+"/.npmrc".
193
194 Note that this must be provided either in the cli or env settings. Once the
195 userconfig is read, it is irrelevant.
196
197 ### globalconfig
198
199 The default global configuration file is resolved based on the location of the
200 node executable. It is process.execPath+"/../../etc/npmrc". In the canonical
201 NodeJS installation with `make install`, this is `/usr/local/etc/npmrc`. If you
202 put the node binary somewhere else (for instance, if you are using nvm or
203 nave), then it would be resolved relative to that location.
204
205 Note that this must be provided in the cli, env, or userconfig settings. Once
206 the globalconfig is read, this parameter is irrelevant.
207
208 ### global
209
210 If set to some truish value (for instance, by being the last cli flag or being
211 passed a literal `true` or `1`), and the `npm config set` param is being
212 called, then the new configuration paramater is written global config file.
213 Otherwise, they are saved to the user config file.
6f7987b @isaacs Document the 'dev' config
isaacs authored
214
215 ### dev
216
217 If set to a truish value, then it'll install the "devDependencies" as well as
218 "dependencies" when installing a package.
219
220 Note that devDependencies are *always* installed when linking a package.
bef47ee @isaacs document "tar" conf
isaacs authored
221
222 ### tar
223
224 Default: env.TAR or "tar"
225
226 The name of a GNU-compatible tar program on your system.
fcd9f2b @isaacs Document "gzip" config
isaacs authored
227
228 ### gzip
229
3cb1bc0 @isaacs Fix #203. Use the env.GZIPBIN env instead of env.GZIP
isaacs authored
230 Default: env.GZIPBIN or "gzip"
fcd9f2b @isaacs Document "gzip" config
isaacs authored
231
232 The name of a GNU-compatible gzip program on your system.
8f3ee0c @isaacs document the 'usage' config
isaacs authored
233
234 ### usage
235
236 If set to `true`, then this will tell help to print out the short usage statement
237 instead of the long manpage type thing.
238
239 This is set automatically if you invoke help like `npm command -?`.
20ba54c @isaacs Document "viewer" config
isaacs authored
240
241 ### viewer
242
243 Default: "man"
244
245 The program to use to view help content. Set to "woman" to use the emacs troff viewer
246 by that name.
c24e212 @isaacs Document new config values
isaacs authored
247
248 ### exit
249
250 Default: true
251
252 Whether or not to exit the process when the command is finished. When
253 using npm programmatically, it's a good idea to set this to `false`
254 explicitly.
255
256 ### logfd
257
258 Default: Standard Error FD (2)
259
260 The file descriptor (integer) or stream object where npm will write log
261 messages.
262
263 When using npm programmatically, you may want to provide a
264 FileWriteStream, or some other form of WritableStream.
265
266 ### outfd
267
268 Default: Standard Output FD (1)
269
270 The file descriptor (integer) or stream object where npm will write
271 "normal" output. For instance, the `ls` and `view` commands write their
272 output here.
273
274 When using npm programmatically, you may want to provide a
275 FileWriteStream, or some other form of WritableStream.
276
277 ### color
278
279 Default: true
280
281 Set to false to disable colorized output.
282
283 In versions of node that expose the `isatty` function, npm will never
284 write colorized output to a non-terminal file descriptor.
285
286 ### tmproot
287
288 Default: env.TMPDIR or "/tmp"
289
290 The folder where temporary files should be placed.
291
292 npm creates a subfolder whenever it is run, and attempts to delete it
293 afterwards.
294
295 ### force
296
297 Default: false
298
299 Set to a truish value to force uninstalling packages, even if they have
300 dependents.
301
302 Note that setting `recursive` is safer, because forcing uninstall can
303 create orphan packages that no longer function properly.
304
305 ### editor
306
307 Default: env.EDITOR
308
309 The program to use to edit files.
Something went wrong with that request. Please try again.