Node.js Command-line API: Options and Permissions

1. Introduction

The Node.js Command-line API exposes built-in debugging tools, multiple ways to execute scripts, and runtime configuration options. Running man node in a terminal displays the manual page for these options.

2. Synopsis

node [options] [V8 options] [ | -e "script" | -] [--] [arguments]
node inspect [ | -e "script" | :] …
node --v8-options

Executing node without arguments starts the REPL environment.

3. Program Entry Point

• Resolved relative to the current working directory if not absolute.
• Loaded via require() unless conditions force ECMAScript module loader (e.g., --import, .mjs/.mts/.wasm extensions, or package.json with "type": "module").

4. General Options

• -: Alias for stdin, script read from input stream.
• --: Marks the end of Node.js options, subsequent arguments passed to the script.
• --abort-on-uncaught-exception: Generates a core file for debugging instead of exiting.

5. Permission Model Options

Node.js introduces a Permission Model to restrict sensitive operations. Flags must be explicitly passed to enable them.

• --allow-addons: Enables loading native addons. Without it, requiring addons throws ERR_DLOPEN_DISABLED.
• --allow-child-process: Allows spawning child processes. Without it, attempts throw ERR_ACCESS_DENIED.
• --allow-fs-read: Grants read access to specified paths. Multiple flags can be used for multiple directories.
• --allow-fs-write: Grants write access to specified paths. Comma-delimited paths are deprecated.
• --allow-inspector: Allows connecting through the inspector protocol. Without it, attempts throw ERR_ACCESS_DENIED.

6. Examples

// Example: Allow reading from all paths
$ node --permission --allow-fs-read=* index.js

// Example: Allow child processes
$ node --permission --allow-child-process index.js

// Example: Enable inspector
$ node --permission --allow-inspector index.js

7. Important Notes

• Options can use dashes or underscores interchangeably (e.g., --pending-deprecation == --pending_deprecation).
• Options passed on the command line override those in NODE_OPTIONS.
• Repeated options use the last provided value.

Conclusion

The Node.js Command-line API provides developers with powerful tools to configure runtime behavior and enforce security through the Permission Model. Understanding and using flags like --allow-addons, --allow-child-process, and --allow-fs-read/write ensures applications run securely and efficiently.

1. Permission Model Options

• --allow-net: Grants network access. Without it, any network attempt throws ERR_ACCESS_DENIED.
• --allow-wasi: Allows creation of WASI instances. Without it, calls throw ERR_ACCESS_DENIED.
• --allow-worker: Enables creation of worker threads. Without it, calls throw ERR_ACCESS_DENIED.

2. Snapshot Options

• --build-snapshot: Creates a snapshot of the application state and saves it to a blob file.
• --build-snapshot-config: Uses a JSON configuration file to control snapshot behavior (e.g., builder, withoutCodeCache).

3. Syntax and Completion

• -c, --check: Performs syntax check without executing the script.
• --completion-bash: Generates a Bash completion script for Node.js.
• -C condition, --conditions=condition: Defines custom conditions for module resolution.

4. CPU Profiling

• --cpu-prof: Starts the V8 CPU profiler and writes output to disk.
• --cpu-prof-dir: Specifies the directory for CPU profile files.
• --cpu-prof-interval: Sets sampling interval in microseconds (default: 1000).
• --cpu-prof-name: Defines the file name template for CPU profiles.

5. Diagnostic and Security Options

• --diagnostic-dir: Sets the directory for diagnostic output files.
• --disable-proto=mode: Disables Object.prototype.__proto__ (delete or throw).
• --disable-sigusr1: Disables debugging via SIGUSR1 signal.
• --disable-warning=code-or-type: Suppresses warnings by code or type (e.g., DeprecationWarning, ExperimentalWarning).

6. Examples

// Allow network access
$ node --permission --allow-net index.js

// Build snapshot
$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js

// CPU profiling
$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js

// Disable specific warning
$ node --disable-warning=DEP0025 index.js

Conclusion

Advanced CLI options in Node.js provide powerful tools for managing security, performance, and debugging. Flags like --allow-net, --build-snapshot, and --cpu-prof help developers build scalable, secure, and efficient applications.

1. WebAssembly Options

• --disable-wasm-trap-handler: Disables trap-handler optimization for WebAssembly. This allows execution on systems with limited virtual memory, though with reduced performance.

2. Code Generation Restrictions

• --disallow-code-generation-from-strings: Makes features like eval and new Function throw exceptions when generating code from strings. This improves security.

3. DNS Options

• --dns-result-order: Sets default order in dns.lookup() and dnsPromises.lookup(). Valid values: ipv4first, ipv6first, verbatim.

4. Security and Networking

• --enable-fips: Enables FIPS-compliant crypto at startup (requires FIPS-compatible OpenSSL).
• --enable-network-family-autoselection: Enables automatic network family selection unless explicitly disabled.

5. Source Maps

• --enable-source-maps: Enables Source Map support for stack traces, mapping transpiled code back to original source files. May introduce latency if Error.stack is accessed frequently.

6. Entry Point Options

• --entry-url: Interprets the program entry point as a URL instead of a file path. Follows ECMAScript module resolution rules.

7. Environment File Options

• --env-file: Loads environment variables from a file. Throws an error if the file does not exist.
• --env-file-if-exists: Same as --env-file but does not throw an error if the file is missing.

8. Eval Option

• -e, --eval "script": Evaluates JavaScript code directly from the command line. On Windows " must be used for quoting.

9. Experimental Features

• --experimental-addon-modules: Experimental import support for .node addons.
• --experimental-config-file: Loads a JSON configuration file to apply Node.js settings.
• --experimental-default-config-file: Automatically loads node.config.json from the current directory.
• --experimental-eventsource: Enables global EventSource API.
• --experimental-import-meta-resolve: Adds support for import.meta.resolve() with a parentURL argument.
• --experimental-inspector-network-resource: Experimental support for inspector network resources.

10. Examples

// Run WebAssembly without trap-handler optimization
$ node --disable-wasm-trap-handler index.js

// Load environment variables
$ node --env-file=.env --env-file=.development.env index.js

// Execute JavaScript directly
$ node -e "console.log('Hello World')"

// Enable Source Maps
$ node --enable-source-maps index.js

Conclusion

Advanced CLI options in Node.js provide powerful tools for managing security, configuration, and experimental features. Flags like --disable-wasm-trap-handler, --enable-source-maps, and --experimental-config-file help developers build secure, debuggable, and flexible applications.

1. Experimental Loader

• --experimental-loader=module: Specifies a module with customization hooks. Discouraged and may be removed in future versions.

2. Networking and Protocols

• --experimental-network-inspection: Experimental support for network inspection with Chrome DevTools.
• --experimental-quic: Enables experimental support for the QUIC protocol.

3. Module and Language Features

• --experimental-require-module: Supports loading synchronous ES module graphs via require().
• --experimental-shadow-realm: Enables ShadowRealm support.
• --experimental-transform-types: Transforms TypeScript-only syntax into JavaScript. Implies --enable-source-maps.
• --experimental-vm-modules: Enables ES module support in the node:vm module.
• --experimental-wasi-unstable-preview1: Enables experimental WASI support.

4. Testing Features

• --experimental-test-coverage: Generates code coverage reports when using the node:test module.
• --experimental-test-module-mocks: Enables module mocking in the test runner.

5. SEA and Config

• --experimental-sea-config: Generates a blob for building single-executable applications.

6. Inspection

• --experimental-worker-inspection: Experimental support for worker inspection with Chrome DevTools.

7. Garbage Collection

• --expose-gc: Exposes the gc() function from V8 for manual garbage collection.

8. Security Flags

• --force-context-aware: Prevents loading native addons that are not context-aware.
• --force-fips: Forces FIPS-compliant crypto at startup.
• --force-node-api-uncaught-exceptions-policy: Enforces proper uncaughtException behavior in Node-API callbacks.
• --frozen-intrinsics: Freezes built-in objects like Array and Object to prevent modification.

9. Heap Profiling

• --heap-prof: Starts the V8 heap profiler and writes output to disk.
• --heap-prof-dir: Specifies the directory for heap profiles.
• --heap-prof-interval: Sets average sampling interval in bytes (default: 512 KB).
• --heap-prof-name: Defines the file name for heap profiles.

10. Heap Snapshots

• --heapsnapshot-near-heap-limit=max_count: Writes heap snapshots when usage approaches the limit.
• --heapsnapshot-signal=signal: Writes a heap dump when the specified signal is received.

11. Help Option

• -h, --help: Prints Node.js command-line options.

Examples

// Enable heap profiling
$ node --heap-prof index.js

// Generate snapshots near heap limit
$ node --heapsnapshot-near-heap-limit=3 index.js

// Display help
$ node --help

Conclusion

Experimental and profiling CLI options in Node.js provide developers with tools to test new features, enforce security, and analyze performance. Flags like --experimental-quic, --heap-prof, and --expose-gc help build more stable and secure applications.

1. Module and Import Options

• --icu-data-dir=file: Specifies the ICU data load path.
• --import=module: Preloads ES modules at startup. --require modules run before --import.
• --input-type=type: Configures how --eval or STDIN input is interpreted (commonjs, module, typescript).

2. HTTP and Parser Options

• --insecure-http-parser: Enables lenient parsing of HTTP requests. This may allow interoperability but is insecure.

3. Inspector and Debugging

• --inspect: Activates the V8 inspector on host:port.
• --inspect-brk: Activates inspector and breaks at the start of the script.
• --inspect-port: Sets host:port for inspector.
• --inspect-wait: Activates inspector and waits for debugger to attach.
• --inspect-publish-uid: Configures how the inspector URL is exposed.

4. Interactive and Execution Options

• -i, --interactive: Opens REPL even if stdin is not a terminal.
• --jitless: Disables runtime allocation of executable memory. Improves security but reduces performance.
• --localstorage-file=file: Specifies the file used to store localStorage data.

5. Memory Management

• --max-http-header-size=size: Sets maximum HTTP header size (default: 16 KiB).
• --max-old-space-size-percentage: Allocates a percentage of system memory to the V8 heap.

6. Security and Addons

• --no-addons: Disables native addons.
• --no-deprecation: Suppresses deprecation warnings.
• --no-warnings: Suppresses all warnings.
• --permission: Enables the Permission Model to restrict access to filesystem, network, child processes, workers, WASI, and addons.

7. OpenSSL Options

• --openssl-config=file: Loads an OpenSSL configuration file.
• --openssl-legacy-provider: Enables the legacy provider in OpenSSL 3.0.
• --openssl-shared-config: Enables the default OpenSSL configuration section.

8. Symlink Options

• --preserve-symlinks: Preserves symlink paths when loading modules.
• --preserve-symlinks-main: Applies the same behavior to the main module.

9. Profiling and Reports

• --prof: Generates V8 profiler output.
• --prof-process: Processes V8 profiler output.
• --redirect-warnings=file: Writes warnings to a file instead of stderr.
• --report-compact: Generates reports in compact JSON format.
• --report-dir: Specifies the directory for diagnostic reports.
• --report-exclude-env: Excludes environment variables from diagnostic reports.

Examples

// Enable inspector on a random port
$ node --inspect=0 index.js

// Preload an ES module at startup
$ node --import=module.js index.js

// Open REPL even without a terminal
$ node -i

// Suppress all warnings
$ node --no-warnings index.js

Conclusion

CLI options in Node.js provide powerful tools for module management, debugging, and security. Flags like --inspect, --permission, and --openssl-config help developers build safer and more debuggable applications.

1. Diagnostic Report Options

• --report-exclude-network: Excludes network interface information from diagnostic reports.
• --report-filename=filename: Sets the filename for the report (stdout or stderr also supported).
• --report-on-fatalerror: Generates a report on fatal errors such as out-of-memory.
• --report-on-signal: Generates a report when a specific signal is received.
• --report-signal=signal: Sets the signal for report generation (default: SIGUSR2).
• --report-uncaught-exception: Generates a report when the process exits due to an uncaught exception.

2. Module Preloading

• -r, --require module: Preloads a specified module at startup. Runs before --import.

3. Run Scripts

• --run: Executes scripts defined in package.json. Simpler and faster than npm run but intentionally limited.

4. Secure Heap Options

• --secure-heap=n: Initializes a secure heap in OpenSSL for sensitive allocations.
• --secure-heap-min=n: Sets the minimum allocation size from the secure heap.

5. Snapshot Options

• --snapshot-blob=path: Specifies the path for saving or loading snapshot blobs.

6. Test Runner Options

• --test: Starts the Node.js test runner.
• --test-concurrency: Sets maximum concurrent test files.
• --test-coverage-branches/functions/lines: Requires minimum coverage thresholds for branches, functions, and lines.
• --test-coverage-include / --test-coverage-exclude: Includes or excludes files from coverage reports using glob patterns.
• --test-force-exit: Forces process exit after all tests finish.
• --test-global-setup=module: Loads a module for global setup before tests run.
• --test-isolation=mode: Configures test isolation (process or none).
• --test-name-pattern / --test-skip-pattern: Runs or skips tests based on regex patterns.
• --test-only: Runs only tests marked with only.
• --test-reporter / --test-reporter-destination: Sets the test reporter and its output destination.
• --test-rerun-failures: Re-runs failed tests using a persisted state file.
• --test-shard: Splits the test suite into equal parts and runs a specific shard.

Examples

// Generate report on fatal errors
$ node --report-on-fatalerror index.js

// Run tests with process isolation
$ node --test --test-isolation=process

// Run only tests marked with "only"
$ node --test --test-only

// Execute the "test" script from package.json
$ node --run test

Conclusion

CLI options in Node.js for diagnostic reporting and test management provide powerful tools for analyzing issues and running secure, stable test suites. Flags like --report-on-fatalerror, --test-coverage-lines, and --secure-heap help developers gain deeper insights and enforce reliable testing practices.