1--- 2title: npm-pkg 3section: 1 4description: Manages your package.json 5--- 6 7### Synopsis 8 9```bash 10npm pkg set <key>=<value> [<key>=<value> ...] 11npm pkg get [<key> [<key> ...]] 12npm pkg delete <key> [<key> ...] 13npm pkg set [<array>[<index>].<key>=<value> ...] 14npm pkg set [<array>[].<key>=<value> ...] 15npm pkg fix 16``` 17 18### Description 19 20A command that automates the management of `package.json` files. 21`npm pkg` provide 3 different sub commands that allow you to modify or retrieve 22values for given object keys in your `package.json`. 23 24The syntax to retrieve and set fields is a dot separated representation of 25the nested object properties to be found within your `package.json`, it's the 26same notation used in [`npm view`](/commands/npm-view) to retrieve information 27from the registry manifest, below you can find more examples on how to use it. 28 29Returned values are always in **json** format. 30 31* `npm pkg get <field>` 32 33 Retrieves a value `key`, defined in your `package.json` file. 34 35 For example, in order to retrieve the name of the current package, you 36 can run: 37 38 ```bash 39 npm pkg get name 40 ``` 41 42 It's also possible to retrieve multiple values at once: 43 44 ```bash 45 npm pkg get name version 46 ``` 47 48 You can view child fields by separating them with a period. To retrieve 49 the value of a test `script` value, you would run the following command: 50 51 ```bash 52 npm pkg get scripts.test 53 ``` 54 55 For fields that are arrays, requesting a non-numeric field will return 56 all of the values from the objects in the list. For example, to get all 57 the contributor emails for a package, you would run: 58 59 ```bash 60 npm pkg get contributors.email 61 ``` 62 63 You may also use numeric indices in square braces to specifically select 64 an item in an array field. To just get the email address of the first 65 contributor in the list, you can run: 66 67 ```bash 68 npm pkg get contributors[0].email 69 ``` 70 71 For complex fields you can also name a property in square brackets 72 to specifically select a child field. This is especially helpful 73 with the exports object: 74 75 ```bash 76 npm pkg get "exports[.].require" 77 ``` 78 79* `npm pkg set <field>=<value>` 80 81 Sets a `value` in your `package.json` based on the `field` value. When 82 saving to your `package.json` file the same set of rules used during 83 `npm install` and other cli commands that touches the `package.json` file 84 are used, making sure to respect the existing indentation and possibly 85 applying some validation prior to saving values to the file. 86 87 The same syntax used to retrieve values from your package can also be used 88 to define new properties or overriding existing ones, below are some 89 examples of how the dot separated syntax can be used to edit your 90 `package.json` file. 91 92 Defining a new bin named `mynewcommand` in your `package.json` that points 93 to a file `cli.js`: 94 95 ```bash 96 npm pkg set bin.mynewcommand=cli.js 97 ``` 98 99 Setting multiple fields at once is also possible: 100 101 ```bash 102 npm pkg set description='Awesome package' engines.node='>=10' 103 ``` 104 105 It's also possible to add to array values, for example to add a new 106 contributor entry: 107 108 ```bash 109 npm pkg set contributors[0].name='Foo' contributors[0].email='foo@bar.ca' 110 ``` 111 112 You may also append items to the end of an array using the special 113 empty bracket notation: 114 115 ```bash 116 npm pkg set contributors[].name='Foo' contributors[].name='Bar' 117 ``` 118 119 It's also possible to parse values as json prior to saving them to your 120 `package.json` file, for example in order to set a `"private": true` 121 property: 122 123 ```bash 124 npm pkg set private=true --json 125 ``` 126 127 It also enables saving values as numbers: 128 129 ```bash 130 npm pkg set tap.timeout=60 --json 131 ``` 132 133* `npm pkg delete <key>` 134 135 Deletes a `key` from your `package.json` 136 137 The same syntax used to set values from your package can also be used 138 to remove existing ones. For example, in order to remove a script named 139 build: 140 141 ```bash 142 npm pkg delete scripts.build 143 ``` 144 145* `npm pkg fix` 146 147 Auto corrects common errors in your `package.json`. npm already 148 does this during `publish`, which leads to subtle (mostly harmless) 149 differences between the contents of your `package.json` file and the 150 manifest that npm uses during installation. 151 152### Workspaces support 153 154You can set/get/delete items across your configured workspaces by using the 155[`workspace`](/using-npm/config#workspace) or 156[`workspaces`](/using-npm/config#workspaces) config options. 157 158For example, setting a `funding` value across all configured workspaces 159of a project: 160 161```bash 162npm pkg set funding=https://example.com --ws 163``` 164 165When using `npm pkg get` to retrieve info from your configured workspaces, the 166returned result will be in a json format in which top level keys are the 167names of each workspace, the values of these keys will be the result values 168returned from each of the configured workspaces, e.g: 169 170``` 171npm pkg get name version --ws 172{ 173 "a": { 174 "name": "a", 175 "version": "1.0.0" 176 }, 177 "b": { 178 "name": "b", 179 "version": "1.0.0" 180 } 181} 182``` 183 184### Configuration 185 186#### `force` 187 188* Default: false 189* Type: Boolean 190 191Removes various protections against unfortunate side effects, common 192mistakes, unnecessary performance degradation, and malicious input. 193 194* Allow clobbering non-npm files in global installs. 195* Allow the `npm version` command to work on an unclean git repository. 196* Allow deleting the cache folder with `npm cache clean`. 197* Allow installing packages that have an `engines` declaration requiring a 198 different version of npm. 199* Allow installing packages that have an `engines` declaration requiring a 200 different version of `node`, even if `--engine-strict` is enabled. 201* Allow `npm audit fix` to install modules outside your stated dependency 202 range (including SemVer-major changes). 203* Allow unpublishing all versions of a published package. 204* Allow conflicting peerDependencies to be installed in the root project. 205* Implicitly set `--yes` during `npm init`. 206* Allow clobbering existing values in `npm pkg` 207* Allow unpublishing of entire packages (not just a single version). 208 209If you don't have a clear idea of what you want to do, it is strongly 210recommended that you do not use this option! 211 212 213 214#### `json` 215 216* Default: false 217* Type: Boolean 218 219Whether or not to output JSON data, rather than the normal output. 220 221* In `npm pkg set` it enables parsing set values with JSON.parse() before 222 saving them to your `package.json`. 223 224Not supported by all npm commands. 225 226 227 228#### `workspace` 229 230* Default: 231* Type: String (can be set multiple times) 232 233Enable running a command in the context of the configured workspaces of the 234current project while filtering by running only the workspaces defined by 235this configuration option. 236 237Valid values for the `workspace` config are either: 238 239* Workspace names 240* Path to a workspace directory 241* Path to a parent workspace directory (will result in selecting all 242 workspaces within that folder) 243 244When set for the `npm init` command, this may be set to the folder of a 245workspace which does not yet exist, to create the folder and set it up as a 246brand new workspace within the project. 247 248This value is not exported to the environment for child processes. 249 250#### `workspaces` 251 252* Default: null 253* Type: null or Boolean 254 255Set to true to run the command in the context of **all** configured 256workspaces. 257 258Explicitly setting this to false will cause commands like `install` to 259ignore workspaces altogether. When not set explicitly: 260 261- Commands that operate on the `node_modules` tree (install, update, etc.) 262will link workspaces into the `node_modules` folder. - Commands that do 263other things (test, exec, publish, etc.) will operate on the root project, 264_unless_ one or more workspaces are specified in the `workspace` config. 265 266This value is not exported to the environment for child processes. 267## See Also 268 269* [npm install](/commands/npm-install) 270* [npm init](/commands/npm-init) 271* [npm config](/commands/npm-config) 272* [npm set-script](/commands/npm-set-script) 273* [workspaces](/using-npm/workspaces) 274