npm pkg set / get Errors - Fix "npm error code EUSAGE" on npm pkg

npm pkg reads and writes package.json fields programmatically. In CI it fails when the key path is malformed, the value is not valid for the field, or it is run somewhere there is no package.json.

What this error means

A pipeline step that calls npm pkg set/get/fix (often to stamp a version or engines field) aborts with npm error code EUSAGE or a complaint about the key/value, rather than editing package.json.

npm output

npm error code EUSAGE
npm error npm pkg set <key>=<value> [<key>=<value> ...]
npm error Usage: set a value in the package.json file
npm error   (run "npm pkg get" with no args to dump package.json)

Common causes

Malformed key path or missing value

npm pkg set expects key=value pairs and a dotted/bracket path for nested fields. A missing =, an unquoted value with spaces, or a bad path triggers EUSAGE.

Setting an object/array without JSON typing

Writing a nested object or array needs the --json flag and valid JSON; passing a bare string where an object is expected fails.

No package.json in the working directory

Run in the wrong directory (or before checkout completes), npm pkg has nothing to operate on.

How to fix it

Use the correct key=value syntax

Quote values, dot into nested keys, and use --json for structured values.

Terminal

# scalar
npm pkg set version=1.4.0
# nested key
npm pkg set engines.node=">=20"
# object/array value needs --json
npm pkg set 'publishConfig={"access":"public"}' --json

Run it where package.json lives

Ensure the step runs in the package root (or pass -w <workspace> for a workspace).
For reads, npm pkg get <key> returns JSON - parse it accordingly.
Confirm checkout finished before the step touches package.json.

How to prevent it

Quote values and use --json for objects/arrays.
Run npm pkg from the correct package/workspace root.
Validate the package.json edit (e.g. npm pkg get) after writing.