Node.js Command Line Options - CLI Parameters and Flags

Node.js provides numerous command-line options that allow you to control its behavior, performance, and functionality. Understanding these options is essential for debugging, performance tuning, and configuring your Node.js applications.

Basic Command Line Usage

Running Node.js

# Basic usage
node [options] [script.js] [arguments]

# Examples
node app.js
node --version
node --help
node script.js arg1 arg2

Getting Help

# Show all available options
node --help

# Show version information
node --version
node -v

# Show detailed version information
node --version --verbose

Core Options

Version and Help Options

# Display version
node --version
node -v
# Output: v18.17.0

# Display help
node --help
node -h

# Display detailed help
node --help --verbose

Script Execution Options

# Execute a script
node script.js

# Execute with arguments
node script.js arg1 arg2 arg3

# Execute with environment variables
NODE_ENV=production node app.js

# Execute with custom options
node --max-old-space-size=4096 app.js

Debugging Options

Inspector Options

# Start with inspector enabled
node --inspect app.js

# Start with inspector on specific port
node --inspect=9229 app.js

# Start with inspector on specific host
node --inspect=0.0.0.0:9229 app.js

# Start with inspector and break on start
node --inspect-brk app.js

# Start with inspector and wait for debugger
node --inspect-brk=9229 app.js

Debug Options

# Enable debug mode
node --debug app.js

# Enable debug mode on specific port
node --debug=5858 app.js

# Enable debug mode and break on start
node --debug-brk app.js

Trace Options

# Enable trace events
node --trace-events-enabled app.js

# Trace specific categories
node --trace-events-enabled --trace-event-categories=v8,node app.js

# Trace to file
node --trace-events-enabled --trace-event-file-pattern=trace-%d app.js

Performance Options

Memory Management

# Set max old space size (in MB)
node --max-old-space-size=4096 app.js

# Set max semi space size (in MB)
node --max-semi-space-size=128 app.js

# Set max executable size (in MB)
node --max-executable-size=1024 app.js

# Set max string length
node --max-string-length=16777216 app.js

Garbage Collection

# Enable garbage collection logging
node --trace-gc app.js

# Enable garbage collection with timestamps
node --trace-gc --trace-gc-verbose app.js

# Expose garbage collection
node --expose-gc app.js

# Optimize for size
node --optimize-for-size app.js

CPU Profiling

# Enable CPU profiling
node --prof app.js

# Enable CPU profiling with output file
node --prof --prof-process app.js

# Enable CPU profiling with custom output
node --prof --prof-process --prof-output=profile.txt app.js

Module and Loading Options

Module Resolution

# Preserve symlinks
node --preserve-symlinks app.js

# Preserve symlinks in main module
node --preserve-symlinks-main app.js

# Enable experimental loader
node --experimental-loader ./loader.js app.js

# Enable experimental specifier resolution
node --experimental-specifier-resolution=node app.js

ES Modules

# Enable experimental modules
node --experimental-modules app.mjs

# Enable experimental loader
node --experimental-loader ./loader.mjs app.mjs

# Enable experimental specifier resolution
node --experimental-specifier-resolution=node app.mjs

CommonJS

# Enable experimental require
node --experimental-require app.js

# Enable experimental top-level await
node --experimental-top-level-await app.js

Security Options

Security Policies

# Enable experimental policy
node --experimental-policy policy.json app.js

# Enable experimental policy with integrity
node --experimental-policy policy.json --experimental-policy-integrity=sha256-... app.js

Permissions

# Disable experimental permissions
node --no-experimental-permission app.js

# Enable experimental permissions
node --experimental-permission app.js

Network and I/O Options

Network Options

# Set DNS cache TTL
node --dns-cache-ttl=300 app.js

# Set DNS cache size
node --dns-cache-size=1000 app.js

# Enable experimental fetch
node --experimental-fetch app.js

I/O Options

# Set UV thread pool size
node --uv-thread-pool-size=4 app.js

# Enable experimental worker threads
node --experimental-worker app.js

Environment and Configuration

Environment Variables

# Set NODE_ENV
NODE_ENV=production node app.js

# Set custom environment variables
DEBUG=* node app.js
PORT=3000 node app.js

# Load environment from file
node --env-file=.env app.js

Configuration Files

# Use custom config file
node --config=config.json app.js

# Use custom loader
node --loader=./custom-loader.js app.js

Experimental Features

Experimental Options

# Enable experimental features
node --experimental-json-modules app.js
node --experimental-wasm-modules app.js
node --experimental-import-meta-resolve app.js

# Enable experimental APIs
node --experimental-global-webcrypto app.js
node --experimental-global-navigator app.js

Future Features

# Enable future flags
node --harmony app.js
node --harmony-top-level-await app.js
node --harmony-import-assertions app.js

Practical Examples

Development Server

# Development with debugging
node --inspect --trace-warnings app.js

# Development with hot reload
node --watch app.js

# Development with experimental features
node --experimental-modules --experimental-loader ./loader.mjs app.mjs

Production Server

# Production with performance tuning
node --max-old-space-size=4096 --optimize-for-size app.js

# Production with monitoring
node --trace-events-enabled --trace-event-categories=v8,node app.js

# Production with security
node --experimental-policy policy.json app.js

Debugging Session

# Debug with breakpoints
node --inspect-brk=9229 app.js

# Debug with custom port
node --inspect=0.0.0.0:9229 app.js

# Debug with trace
node --inspect --trace-events-enabled app.js

Performance Analysis

# CPU profiling
node --prof --prof-process app.js

# Memory analysis
node --trace-gc --trace-gc-verbose app.js

# Heap analysis
node --inspect --inspect-brk app.js

Script Arguments

Accessing Arguments

// script.js
console.log('Arguments:', process.argv);

// Command: node script.js arg1 arg2 arg3
// Output: ['node', 'script.js', 'arg1', 'arg2', 'arg3']

Parsing Arguments

// argument-parser.js
const args = process.argv.slice(2);
const options = {};

for (let i = 0; i < args.length; i++) {
  const arg = args[i];
  
  if (arg.startsWith('--')) {
    const key = arg.slice(2);
    const value = args[i + 1];
    options[key] = value || true;
    i++; // Skip next argument as it's the value
  } else if (arg.startsWith('-')) {
    const key = arg.slice(1);
    const value = args[i + 1];
    options[key] = value || true;
    i++; // Skip next argument as it's the value
  }
}

console.log('Parsed options:', options);

Using Commander.js

// commander-example.js
const { program } = require('commander');

program
  .version('1.0.0')
  .description('My CLI application')
  .option('-d, --debug', 'output extra debugging')
  .option('-s, --small', 'small pizza size')
  .option('-p, --pizza-type <type>', 'flavour of pizza')
  .option('-c, --cheese <type>', 'add extra cheese', 'mozzarella')
  .option('-C, --no-cheese', 'remove cheese')
  .parse(process.argv);

const options = program.opts();
console.log('Options:', options);

Environment-Specific Configurations

Development

# .env.development
NODE_ENV=development
DEBUG=*
PORT=3000
LOG_LEVEL=debug

# Run with development config
node --env-file=.env.development app.js

Production

# .env.production
NODE_ENV=production
PORT=8080
LOG_LEVEL=error
MAX_CONNECTIONS=1000

# Run with production config
node --env-file=.env.production app.js

Testing

# .env.test
NODE_ENV=test
PORT=3001
LOG_LEVEL=silent
DB_URL=sqlite://:memory:

# Run with test config
node --env-file=.env.test app.js

Best Practices

1. Use Appropriate Options

# Good: Use specific options for your use case
node --inspect --max-old-space-size=2048 app.js

# Bad: Use unnecessary options
node --inspect --debug --trace-gc --prof app.js

2. Document Your Options

# Create a start script in package.json
{
  "scripts": {
    "start": "node app.js",
    "start:dev": "node --inspect --watch app.js",
    "start:prod": "node --max-old-space-size=4096 --optimize-for-size app.js",
    "debug": "node --inspect-brk=9229 app.js"
  }
}

3. Use Environment Variables

# Use environment variables for configuration
NODE_ENV=production PORT=8080 node app.js

# Or use .env files
node --env-file=.env app.js

4. Monitor Performance

# Use performance monitoring in production
node --trace-events-enabled --trace-event-categories=v8,node app.js

Troubleshooting

Common Issues

Memory Issues

# Increase memory limit
node --max-old-space-size=4096 app.js

Debugging Issues

# Use inspector instead of debug
node --inspect app.js

Module Loading Issues

# Use experimental loader
node --experimental-loader ./loader.js app.js

Performance Issues
```
# Enable profiling
node --prof app.js
```

Next Steps

Now that you understand Node.js command line options, you're ready to:

Node.js - Package Manager (NPM) - Learn package management
Node.js - Callbacks Concept - Understand callback functions
Node.js - Events - Learn event-driven programming
Node.js - Event Loop - Understand the event loop

Command Line Options Mastery Complete! You now know how to use Node.js CLI options effectively for debugging, performance tuning, and configuration. These options are essential for professional Node.js development!

Basic Command Line Usage​

Running Node.js​

Getting Help​

Core Options​

Version and Help Options​

Script Execution Options​

Debugging Options​

Inspector Options​

Debug Options​

Trace Options​

Performance Options​

Memory Management​

Garbage Collection​

CPU Profiling​

Module and Loading Options​

Module Resolution​

ES Modules​

CommonJS​

Security Options​

Security Policies​

Permissions​

Network and I/O Options​

Network Options​

I/O Options​

Environment and Configuration​

Environment Variables​

Configuration Files​

Experimental Features​

Experimental Options​

Future Features​

Practical Examples​

Development Server​

Production Server​

Debugging Session​

Performance Analysis​

Script Arguments​

Accessing Arguments​

Parsing Arguments​

Using Commander.js​

Environment-Specific Configurations​

Development​

Production​

Testing​

Best Practices​

1. Use Appropriate Options​

2. Document Your Options​

3. Use Environment Variables​

4. Monitor Performance​

Troubleshooting​

Common Issues​

Next Steps​