Introduction

Passing command-line arguments to an npm script is mostly about understanding one rule: use -- so npm stops processing flags itself and forwards the rest to the underlying command. Once that boundary is clear, script argument handling becomes predictable in local development, CI, and nested script chains.

The actual script can then read the forwarded values from process.argv or through a dedicated argument parser. The forwarding step and the parsing step are separate concerns.

Forward Arguments With --

Suppose package.json contains:

1{
2  "scripts": {
3    "start": "node app.js"
4  }
5}

To pass flags to app.js, write:

npm run start -- --mode=production --port=8080

Everything after the first -- is forwarded to the script command instead of being interpreted by npm itself.

Read the Arguments in Node

Inside the script, the raw values appear in process.argv:

console.log(process.argv);

For many small scripts, a tiny helper is enough:

1function getArg(name) {
2  const prefix = `--${name}=`;
3  const found = process.argv.find(value => value.startsWith(prefix));
4  return found ? found.slice(prefix.length) : null;
5}
6
7const mode = getArg("mode") ?? "development";
8const port = Number(getArg("port") ?? "3000");
9
10console.log({ mode, port });

This works well when the script has only a few options and you control all call sites.

Use a Parser for Nontrivial Scripts

Once flags become more complex, use an argument parser instead of hand-rolled string checks:

npm install minimist

1const minimist = require("minimist");
2
3const args = minimist(process.argv.slice(2), {
4  string: ["mode"],
5  default: { mode: "development", port: 3000 }
6});
7
8console.log(args.mode, args.port);

This is easier to extend and less fragile than maintaining custom parsing logic forever.

Nested npm Scripts Need Forwarding Too

If one npm script calls another, arguments do not automatically survive unless you forward them:

1{
2  "scripts": {
3    "build": "npm run build:app --",
4    "build:app": "node scripts/build.js"
5  }
6}

Now this works:

npm run build -- --target=web

If the intermediate script forgets the extra --, the downstream script never sees the flags.

CLI Flags Versus Environment Variables

Not every setting belongs in a command-line argument. A useful split is:

• use CLI flags for per-run toggles such as --watch or --port
• use environment variables for secrets or broader environment configuration

Example:

1{
2  "scripts": {
3    "start:prod": "cross-env NODE_ENV=production node app.js"
4  }
5}

Then add ordinary runtime flags on top:

npm run start:prod -- --port=8080

That keeps secrets out of the command line while preserving flexible runtime options.

Common Pitfalls

The biggest mistake is forgetting the -- separator and then wondering why the script never receives the extra arguments.

Another common issue is parsing process.argv without remembering that the first entries belong to the Node executable and script path.

Developers also lose arguments in nested npm scripts because an intermediate script forgot to forward them explicitly.

Finally, be careful with sensitive values. Command-line arguments can end up in logs, CI output, or process listings, so secrets should usually be passed through environment variables or a secret store instead.

Summary

• Use npm run <script> -- <args> to forward command-line arguments to the actual script.
• Read the forwarded values from process.argv or use a parser library for larger scripts.
• Forward arguments explicitly again when one npm script calls another.
• Use CLI flags for per-run options and environment variables for sensitive or broader configuration.
• Treat the forwarding rule and the parsing strategy as separate parts of the solution.