npm run: pass script flags after --

Locate the error-producing parser

Check whether the failure appears before the configured script starts. An npm option error differs from an application rejecting its own flag after launch. Preserve the exact argument order in the reproduction.

For our inspect script, placing --format=json before the separator caused npm 12.2.1 to reject an abbreviated flag and suggest a different npm configuration name. No application argument parsing occurred in that failed call.

Use a minimal argument probe

Save this local diagnostic script as inspect.cjs. It prints only arguments deliberately passed to it; do not use real secrets as command-line test values.

The probe’s output makes argument forwarding observable without depending on a test runner or framework’s own option semantics.

javascript · EXAMPLE

console.log(JSON.stringify(process.argv.slice(2)));

Define the script entry explicitly

Add the following script definition to a disposable test package or inspect the equivalent entry in your project. Keep the application command distinct from npm’s script name.

This example uses a plain Node script. It does not validate what a real compiler or test runner does with format options after receiving them.

json · EXAMPLE

{
  "name": "argument-probe",
  "private": true,
  "scripts": {
    "inspect": "node inspect.cjs"
  }
}

Forward the option after the separator

Put npm options such as --silent before --, then place the application option after it. In the corrected fixture, stdout was the JSON array containing exactly --format=json.

The first command below is the corrected path. The second deliberately demonstrates the observed npm 12 failure and should be run separately when reproducing the parser distinction.

sh · EXAMPLE

npm run inspect --silent -- --format=json
# Expected npm 12.2.1 parsing failure for this fixture:
npm run inspect --silent --format=json

Verify the real script’s behavior

Argument delivery is only the first boundary. Next confirm that the actual program recognizes the option and produces the intended behavior, such as selecting the requested test subset or output format.

Keep version-specific error wording separate from the general forwarding contract. An older npm that warns or consumes an option differently still needs an explicit script argument boundary. Test the same command used by CI rather than a differently ordered local substitute.

Know the limits

Reproduced with npm 12.2.1 and Node.js 24.22.1 in a disposable Linux container using local fixtures, with external networking disabled during tests. npm run inspect --format=json was rejected as an invalid abbreviated npm flag. After --, the script received --format=json unchanged. This records npm 12.2.1 behavior for that option; older versions or other options can fail or be interpreted differently.

Sources & further reading

A technical publication by CoreTrailKit.

Browse all articles