diff --git a/doc/api/cli.md b/doc/api/cli.md index fa7db08d71dd..074f6ea6df90 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -1497,8 +1497,8 @@ added: v26.4.0 > Stability: 1 - Experimental Enable the experimental [`node:vfs`][] module. This flag also gates the -[`--vfs-mount`][] startup flag, which is only allowed when `--experimental-vfs` -is set. +[`--vfs-mount`][] and [`--vfs-load`][] startup flags, which are only allowed +when `--experimental-vfs` is set. ### `--experimental-vm-modules` @@ -3564,6 +3564,38 @@ added: v0.1.3 Print node's version. +### `--vfs-load` + + + +Requires [`--experimental-vfs`][] and at least one [`--vfs-mount`][]. + +Runs the entry point (`process.argv[1]`) and all subsequent +`require()`/`import` resolution against the **last** [`--vfs-mount`][] rather +than the real file system. `process.argv[1]` becomes that mount's root, as if +`node ` had been run: the mount's own `package.json` `"main"` (or +`index.js`) selects the entry point, and any positional command-line argument +is the program's own (available from `process.argv[2]` onward), never an +entry-point override. + +Module resolution under the loaded mount is fully sandboxed: `package.json` +lookups, `node_modules`-style resolution, and legacy `main` resolution never +fall back to the real file system once they would step outside the mount. + +Combined with a self-mounting shebang this makes an archive directly +executable. The kernel appends the script's own path as the trailing argument, +which the final `--vfs-mount` consumes as its source, so the archive mounts +itself and runs (the ZIP is located by its trailing record, so the shebang +prefix is ignored): + +```console +$ (printf '#!/usr/bin/env -S node --vfs-load --vfs-mount\n'; cat app.zip) > app +$ chmod +x app +$ ./app arg1 arg2 # runs the archive's index.js with ['arg1', 'arg2'] +``` + ### `--vfs-mount=source[=target]`