From 9b82f97ee72f8510d8d5a45a33928a2835859bd7 Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Mon, 21 Jul 2025 19:05:49 +0200
Subject: [PATCH 1/2] cli: add --use-env-proxy

This does the same as NODE_USE_ENV_PROXY. When both are set,
like other options that can be configured from both sides,
the CLI flag takes precedence.
---
 doc/api/cli.md                                |  19 +++
 doc/api/errors.md                             |   2 +-
 doc/api/http.md                               |  16 ++-
 doc/node-config-schema.json                   |   3 +
 doc/node.1                                    |   3 +
 lib/_http_agent.js                            |   4 +-
 lib/https.js                                  |   4 +-
 lib/internal/process/pre_execution.js         |  29 +++--
 src/node_options.cc                           |   8 ++
 src/node_options.h                            |   1 +
 test/client-proxy/test-http-proxy-request.mjs |   2 -
 .../client-proxy/test-https-proxy-request.mjs |   2 -
 .../test-use-env-proxy-cli-http.mjs           |  75 +++++++++++
 .../test-use-env-proxy-cli-https.mjs          |  81 ++++++++++++
 .../test-use-env-proxy-precedence.mjs         | 117 ++++++++++++++++++
 test/common/proxy-server.js                   |   8 +-
 16 files changed, 346 insertions(+), 28 deletions(-)
 create mode 100644 test/client-proxy/test-use-env-proxy-cli-http.mjs
 create mode 100644 test/client-proxy/test-use-env-proxy-cli-https.mjs
 create mode 100644 test/client-proxy/test-use-env-proxy-precedence.mjs

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 6778d3db33bf53..38192350b4c308 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -2999,6 +2999,20 @@ environment variables.
 
 See `SSL_CERT_DIR` and `SSL_CERT_FILE`.
 
+### `--use-env-proxy`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active Development
+
+When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
+environment variables during startup, and tunnels requests over the
+specified proxy.
+
+This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
+
 ### `--use-largepages=mode`
 
 <!-- YAML
@@ -3498,6 +3512,7 @@ one is included in the list below.
 * `--track-heap-objects`
 * `--unhandled-rejections`
 * `--use-bundled-ca`
+* `--use-env-proxy`
 * `--use-largepages`
 * `--use-openssl-ca`
 * `--use-system-ca`
@@ -3653,6 +3668,8 @@ When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
 environment variables during startup, and tunnels requests over the
 specified proxy.
 
+This can also be enabled using the [`--use-env-proxy`][] command-line flag.
+
 This currently only affects requests sent over `fetch()`. Support for other
 built-in `http` and `https` methods is under way.
 
@@ -3984,12 +4001,14 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--print`]: #-p---print-script
 [`--redirect-warnings`]: #--redirect-warningsfile
 [`--require`]: #-r---require-module
+[`--use-env-proxy`]: #--use-env-proxy
 [`AsyncLocalStorage`]: async_context.md#class-asynclocalstorage
 [`Buffer`]: buffer.md#class-buffer
 [`CRYPTO_secure_malloc_init`]: https://www.openssl.org/docs/man3.0/man3/CRYPTO_secure_malloc_init.html
 [`ERR_INVALID_TYPESCRIPT_SYNTAX`]: errors.md#err_invalid_typescript_syntax
 [`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`]: errors.md#err_unsupported_typescript_syntax
 [`NODE_OPTIONS`]: #node_optionsoptions
+[`NODE_USE_ENV_PROXY=1`]: #node_use_env_proxy1
 [`NO_COLOR`]: https://no-color.org
 [`Web Storage`]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API
 [`YoungGenerationSizeFromSemiSpaceSize`]: https://chromium.googlesource.com/v8/v8.git/+/refs/tags/10.3.129/src/heap/heap.cc#328
diff --git a/doc/api/errors.md b/doc/api/errors.md
index 687720d7f42047..ff8c1ef6f9ce21 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -2501,7 +2501,7 @@ Failed to proxy a request because the proxy configuration is invalid.
 
 ### `ERR_PROXY_TUNNEL`
 
-Failed to establish proxy tunnel when `NODE_USE_ENV_PROXY` is enabled.
+Failed to establish proxy tunnel when `NODE_USE_ENV_PROXY` or `--use-env-proxy` is enabled.
 
 <a id="ERR_QUIC_APPLICATION_ERROR"></a>
 
diff --git a/doc/api/http.md b/doc/api/http.md
index af7a1218734793..2148ea36355d17 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -4273,10 +4273,9 @@ added: REPLACEME
 
 > Stability: 1.1 - Active development
 
-When Node.js creates the global agent, it checks the `NODE_USE_ENV_PROXY`
-environment variable. If it is set to `1`, the global agent will be constructed
+When Node.js creates the global agent, if the `NODE_USE_ENV_PROXY` environment variable is
+set to `1` or `--use-env-proxy` is enabled, the global agent will be constructed
 with `proxyEnv: process.env`, enabling proxy support based on the environment variables.
-
 Custom agents can also be created with proxy support by passing a
 `proxyEnv` option when constructing the agent. The value can be `process.env`
 if they just want to inherit the configuration from the environment variables,
@@ -4318,13 +4317,20 @@ Multiple entries should be separated by commas.
 
 ### Example
 
-Starting a Node.js process with proxy support enabled for all requests sent
-through the default global agent:
+To start a Node.js process with proxy support enabled for all requests sent
+through the default global agent, either use the `NODE_USE_ENV_PROXY` environment
+variable:
 
 ```console
 NODE_USE_ENV_PROXY=1 HTTP_PROXY=http://proxy.example.com:8080 NO_PROXY=localhost,127.0.0.1 node client.js
 ```
 
+Or the `--use-env-proxy` flag.
+
+```console
+HTTP_PROXY=http://proxy.example.com:8080 NO_PROXY=localhost,127.0.0.1 node --use-env-proxy client.js
+```
+
 To create a custom agent with built-in proxy support:
 
 ```cjs
diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json
index e280834028c940..7f867e564eba21 100644
--- a/doc/node-config-schema.json
+++ b/doc/node-config-schema.json
@@ -541,6 +541,9 @@
         "use-bundled-ca": {
           "type": "boolean"
         },
+        "use-env-proxy": {
+          "type": "boolean"
+        },
         "use-largepages": {
           "type": "string"
         },
diff --git a/doc/node.1 b/doc/node.1
index 14ce85c9e6c319..3e259bae0e8098 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -603,6 +603,9 @@ See
 and
 .Ev SSL_CERT_FILE .
 .
+.It Fl -use-env-proxy
+Parse proxy settings from HTTP_PROXY/HTTPS_PROXY/NO_PROXY environment variables and apply the setting in global HTTP/HTTPS clients.
+.
 .It Fl -use-largepages Ns = Ns Ar mode
 Re-map the Node.js static code to large memory pages at startup. If supported on
 the target system, this will cause the Node.js static code to be moved onto 2
diff --git a/lib/_http_agent.js b/lib/_http_agent.js
index 86edd8fc0fc68f..ddb6cd7d9a4c03 100644
--- a/lib/_http_agent.js
+++ b/lib/_http_agent.js
@@ -54,6 +54,7 @@ const {
   validateString,
 } = require('internal/validators');
 const assert = require('internal/assert');
+const { getOptionValue } = require('internal/options');
 
 const kOnKeylog = Symbol('onkeylog');
 const kRequestOptions = Symbol('requestOptions');
@@ -622,6 +623,7 @@ module.exports = {
   Agent,
   globalAgent: new Agent({
     keepAlive: true, scheduling: 'lifo', timeout: 5000,
-    proxyEnv: process.env.NODE_USE_ENV_PROXY ? filterEnvForProxies(process.env) : undefined,
+    // This normalized from both --use-env-proxy and NODE_USE_ENV_PROXY settings.
+    proxyEnv: getOptionValue('--use-env-proxy') ? filterEnvForProxies(process.env) : undefined,
   }),
 };
diff --git a/lib/https.js b/lib/https.js
index a78665cf2e7c8c..fd9ae36e7b4d6f 100644
--- a/lib/https.js
+++ b/lib/https.js
@@ -70,6 +70,7 @@ const { URL, urlToHttpOptions, isURL } = require('internal/url');
 const { validateObject } = require('internal/validators');
 const { isIP, isIPv6 } = require('internal/net');
 const assert = require('internal/assert');
+const { getOptionValue } = require('internal/options');
 
 function Server(opts, requestListener) {
   if (!(this instanceof Server)) return new Server(opts, requestListener);
@@ -599,7 +600,8 @@ Agent.prototype._evictSession = function _evictSession(key) {
 
 const globalAgent = new Agent({
   keepAlive: true, scheduling: 'lifo', timeout: 5000,
-  proxyEnv: process.env.NODE_USE_ENV_PROXY ? filterEnvForProxies(process.env) : undefined,
+  // This normalized from both --use-env-proxy and NODE_USE_ENV_PROXY settings.
+  proxyEnv: getOptionValue('--use-env-proxy') ? filterEnvForProxies(process.env) : undefined,
 });
 
 /**
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
index 355c708934e8de..139a66a6d0e508 100644
--- a/lib/internal/process/pre_execution.js
+++ b/lib/internal/process/pre_execution.js
@@ -166,19 +166,24 @@ function prepareExecution(options) {
 }
 
 function setupHttpProxy() {
-  if (process.env.NODE_USE_ENV_PROXY &&
-      (process.env.HTTP_PROXY || process.env.HTTPS_PROXY ||
-       process.env.http_proxy || process.env.https_proxy)) {
-    const { setGlobalDispatcher, EnvHttpProxyAgent } = require('internal/deps/undici/undici');
-    const envHttpProxyAgent = new EnvHttpProxyAgent();
-    setGlobalDispatcher(envHttpProxyAgent);
-    // For fetch, we need to set the global dispatcher from here.
-    // For http/https agents, we'll configure the global agent when they are
-    // actually created, in lib/_http_agent.js and lib/https.js.
-    // TODO(joyeecheung): This is currently guarded with NODE_USE_ENV_PROXY. Investigate whether
-    // it's possible to enable it by default without stepping on other existing libraries that
-    // sets the global dispatcher or monkey patches the global agent.
+  // This normalized from both --use-env-proxy and NODE_USE_ENV_PROXY settings.
+  if (!getOptionValue('--use-env-proxy')) {
+    return;
+  }
+  if (!process.env.HTTP_PROXY && !process.env.HTTPS_PROXY &&
+      !process.env.http_proxy && !process.env.https_proxy) {
+    return;
   }
+
+  const { setGlobalDispatcher, EnvHttpProxyAgent } = require('internal/deps/undici/undici');
+  const envHttpProxyAgent = new EnvHttpProxyAgent();
+  setGlobalDispatcher(envHttpProxyAgent);
+  // For fetch, we need to set the global dispatcher from here.
+  // For http/https agents, we'll configure the global agent when they are
+  // actually created, in lib/_http_agent.js and lib/https.js.
+  // TODO(joyeecheung): This is currently guarded with NODE_USE_ENV_PROXY. Investigate whether
+  // it's possible to enable it by default without stepping on other existing libraries that
+  // sets the global dispatcher or monkey patches the global agent.
 }
 
 function setupUserModules(forceDefaultLoader = false) {
diff --git a/src/node_options.cc b/src/node_options.cc
index 6aaa67c38dfba2..ce287e48c1a46c 100644
--- a/src/node_options.cc
+++ b/src/node_options.cc
@@ -664,6 +664,12 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "emit pending deprecation warnings",
             &EnvironmentOptions::pending_deprecation,
             kAllowedInEnvvar);
+  AddOption("--use-env-proxy",
+            "parse proxy settings from HTTP_PROXY/HTTPS_PROXY/NO_PROXY"
+            "environment variables and apply the setting in global HTTP/HTTPS "
+            "clients",
+            &EnvironmentOptions::use_env_proxy,
+            kAllowedInEnvvar);
   AddOption("--preserve-symlinks",
             "preserve symbolic links when resolving",
             &EnvironmentOptions::preserve_symlinks,
@@ -1878,6 +1884,8 @@ void HandleEnvOptions(std::shared_ptr<EnvironmentOptions> env_options,
   env_options->preserve_symlinks_main =
       opt_getter("NODE_PRESERVE_SYMLINKS_MAIN") == "1";
 
+  env_options->use_env_proxy = opt_getter("NODE_USE_ENV_PROXY") == "1";
+
   if (env_options->redirect_warnings.empty())
     env_options->redirect_warnings = opt_getter("NODE_REDIRECT_WARNINGS");
 }
diff --git a/src/node_options.h b/src/node_options.h
index 8bd537f7d9e149..0d597a45ac22ef 100644
--- a/src/node_options.h
+++ b/src/node_options.h
@@ -242,6 +242,7 @@ class EnvironmentOptions : public Options {
   bool force_repl = false;
 
   bool insecure_http_parser = false;
+  bool use_env_proxy = false;
 
   bool tls_min_v1_0 = false;
   bool tls_min_v1_1 = false;
diff --git a/test/client-proxy/test-http-proxy-request.mjs b/test/client-proxy/test-http-proxy-request.mjs
index b17f4e9581e708..8a35aa7461c37f 100644
--- a/test/client-proxy/test-http-proxy-request.mjs
+++ b/test/client-proxy/test-http-proxy-request.mjs
@@ -78,8 +78,6 @@ if (!common.isWindows) {
     REQUEST_URL: requestUrl,
     http_proxy: `http://localhost:${proxy.address().port}`,
     HTTP_PROXY: `http://localhost:${proxy2.address().port}`,
-  }, {
-    stdout: 'Hello world',
   });
   assert.deepStrictEqual(logs, expectedLogs);
   assert.strictEqual(stderr.trim(), '');
diff --git a/test/client-proxy/test-https-proxy-request.mjs b/test/client-proxy/test-https-proxy-request.mjs
index 074dd9bba197cd..bb3dcc44d9922f 100644
--- a/test/client-proxy/test-https-proxy-request.mjs
+++ b/test/client-proxy/test-https-proxy-request.mjs
@@ -92,8 +92,6 @@ if (!common.isWindows) {
     https_proxy: `http://localhost:${proxy.address().port}`,
     HTTPS_PROXY: `http://localhost:${proxy2.address().port}`,
     NODE_EXTRA_CA_CERTS: fixtures.path('keys', 'fake-startcom-root-cert.pem'),
-  }, {
-    stdout: 'Hello world',
   });
   assert.deepStrictEqual(logs, expectedLogs);
   assert.strictEqual(stderr.trim(), '');
diff --git a/test/client-proxy/test-use-env-proxy-cli-http.mjs b/test/client-proxy/test-use-env-proxy-cli-http.mjs
new file mode 100644
index 00000000000000..c650bb5d69d811
--- /dev/null
+++ b/test/client-proxy/test-use-env-proxy-cli-http.mjs
@@ -0,0 +1,75 @@
+// This tests that --use-env-proxy works the same as NODE_USE_ENV_PROXY=1
+// for HTTP requests using the built-in http module and fetch API.
+
+import * as common from '../common/index.mjs';
+import assert from 'node:assert';
+import http from 'node:http';
+import { once } from 'events';
+import { createProxyServer, runProxiedRequest, checkProxiedFetch } from '../common/proxy-server.js';
+
+// Start a minimal proxy server.
+const { proxy, logs } = createProxyServer();
+proxy.listen(0);
+await once(proxy, 'listening');
+
+delete process.env.NODE_USE_ENV_PROXY; // Ensure the environment variable is not set.
+
+// Start a HTTP server to process the final request.
+const server = http.createServer(common.mustCall((req, res) => {
+  res.end('Hello world');
+}, 2));
+server.on('error', common.mustNotCall((err) => { console.error('Server error', err); }));
+server.listen(0);
+await once(server, 'listening');
+
+const serverHost = `localhost:${server.address().port}`;
+const requestUrl = `http://${serverHost}/test`;
+
+// Tests --use-env-proxy works with http builtins.
+{
+  const { code, signal, stderr, stdout } = await runProxiedRequest({
+    REQUEST_URL: requestUrl,
+    HTTP_PROXY: `http://localhost:${proxy.address().port}`,
+  }, ['--use-env-proxy']);
+  assert.strictEqual(stderr.trim(), '');
+  assert.match(stdout, /Hello world/);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(signal, null);
+  assert.deepStrictEqual(logs, [{
+    method: 'GET',
+    url: requestUrl,
+    headers: {
+      'connection': 'keep-alive',
+      'proxy-connection': 'keep-alive',
+      'host': serverHost,
+    },
+  }]);
+}
+
+// Tests --use-env-proxy works with fetch and http.
+{
+  logs.splice(0, logs.length);
+  await checkProxiedFetch({
+    FETCH_URL: requestUrl,
+    HTTP_PROXY: `http://localhost:${proxy.address().port}`,
+  }, {
+    stdout: 'Hello world',
+  }, ['--use-env-proxy']);
+
+  // FIXME(undici:4083): undici currently always tunnels the request over
+  // CONNECT if proxyTunnel is not explicitly set to false, but what we
+  // need is for it to be automatically false for HTTP requests to be
+  // consistent with curl.
+  assert.deepStrictEqual(logs, [{
+    method: 'CONNECT',
+    url: serverHost,
+    headers: {
+      'connection': 'close',
+      'proxy-connection': 'keep-alive',
+      'host': serverHost,
+    },
+  }]);
+}
+
+server.close();
+proxy.close();
diff --git a/test/client-proxy/test-use-env-proxy-cli-https.mjs b/test/client-proxy/test-use-env-proxy-cli-https.mjs
new file mode 100644
index 00000000000000..950e26d78f7f7e
--- /dev/null
+++ b/test/client-proxy/test-use-env-proxy-cli-https.mjs
@@ -0,0 +1,81 @@
+// This tests that --use-env-proxy works the same as NODE_USE_ENV_PROXY=1
+// for HTTPS requests using the built-in https module and fetch API.
+
+import * as common from '../common/index.mjs';
+import fixtures from '../common/fixtures.js';
+import assert from 'node:assert';
+import { once } from 'events';
+import { createProxyServer, runProxiedRequest, checkProxiedFetch } from '../common/proxy-server.js';
+
+if (!common.hasCrypto) {
+  common.skip('missing crypto');
+}
+
+// https must be dynamically imported so that builds without crypto support
+// can skip it.
+const { default: https } = await import('node:https');
+
+// Start a minimal proxy server.
+const { proxy, logs } = createProxyServer();
+proxy.listen(0);
+await once(proxy, 'listening');
+
+delete process.env.NODE_USE_ENV_PROXY; // Ensure the environment variable is not set.
+// Start a HTTPS server to process the final request.
+const server = https.createServer({
+  cert: fixtures.readKey('agent8-cert.pem'),
+  key: fixtures.readKey('agent8-key.pem'),
+}, common.mustCall((req, res) => {
+  res.end('Hello world');
+}, 2));
+server.on('error', common.mustNotCall((err) => { console.error('Server error', err); }));
+server.listen(0);
+await once(server, 'listening');
+
+const serverHost = `localhost:${server.address().port}`;
+const requestUrl = `https://${serverHost}/test`;
+
+// Tests --use-env-proxy works with https builtins.
+{
+  const { code, signal, stderr, stdout } = await runProxiedRequest({
+    REQUEST_URL: requestUrl,
+    HTTPS_PROXY: `http://localhost:${proxy.address().port}`,
+    NODE_EXTRA_CA_CERTS: fixtures.path('keys', 'fake-startcom-root-cert.pem'),
+  }, ['--use-env-proxy']);
+  assert.strictEqual(stderr.trim(), '');
+  assert.match(stdout, /Hello world/);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(signal, null);
+  assert.deepStrictEqual(logs, [{
+    method: 'CONNECT',
+    url: serverHost,
+    headers: {
+      'proxy-connection': 'keep-alive',
+      'host': serverHost,
+    },
+  }]);
+}
+
+// Tests --use-env-proxy works with fetch and https.
+{
+  logs.splice(0, logs.length);
+  await checkProxiedFetch({
+    FETCH_URL: `https://${serverHost}/test`,
+    HTTPS_PROXY: `http://localhost:${proxy.address().port}`,
+    NODE_EXTRA_CA_CERTS: fixtures.path('keys', 'fake-startcom-root-cert.pem'),
+  }, {
+    stdout: 'Hello world',
+  }, ['--use-env-proxy']);
+  assert.deepStrictEqual(logs, [{
+    method: 'CONNECT',
+    url: serverHost,
+    headers: {
+      'connection': 'close',
+      'proxy-connection': 'keep-alive',
+      'host': serverHost,
+    },
+  }]);
+}
+
+server.close();
+proxy.close();
diff --git a/test/client-proxy/test-use-env-proxy-precedence.mjs b/test/client-proxy/test-use-env-proxy-precedence.mjs
new file mode 100644
index 00000000000000..f75a3c61a424aa
--- /dev/null
+++ b/test/client-proxy/test-use-env-proxy-precedence.mjs
@@ -0,0 +1,117 @@
+// This tests the precedence and interaction between --use-env-proxy CLI flag
+// and NODE_USE_ENV_PROXY environment variable when both are set.
+
+import * as common from '../common/index.mjs';
+import assert from 'node:assert';
+import http from 'node:http';
+import { once } from 'events';
+import { createProxyServer, runProxiedRequest } from '../common/proxy-server.js';
+
+// Start a proxy server for testing
+const { proxy, logs } = createProxyServer();
+proxy.listen(0);
+await once(proxy, 'listening');
+
+// Start a HTTP server to process the final request
+const server = http.createServer(common.mustCall((req, res) => {
+  res.end('Hello world');
+}, 4));
+server.on('error', common.mustNotCall((err) => { console.error('Server error', err); }));
+server.listen(0);
+await once(server, 'listening');
+
+const serverHost = `localhost:${server.address().port}`;
+const requestUrl = `http://${serverHost}/test`;
+
+delete process.env.NODE_USE_ENV_PROXY; // Ensure the environment variable is not set.
+// NODE_USE_ENV_PROXY=1 and --use-env-proxy can be used at the same time.
+{
+  const { code, signal, stderr, stdout } = await runProxiedRequest({
+    NODE_USE_ENV_PROXY: '1',
+    REQUEST_URL: requestUrl,
+    HTTP_PROXY: `http://localhost:${proxy.address().port}`,
+  }, ['--use-env-proxy']);
+
+  assert.strictEqual(stderr.trim(), '');
+  assert.match(stdout, /Hello world/);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(signal, null);
+
+  // Should use the proxy
+  assert.strictEqual(logs.length, 1);
+  assert.deepStrictEqual(logs[0], {
+    method: 'GET',
+    url: requestUrl,
+    headers: {
+      'connection': 'keep-alive',
+      'proxy-connection': 'keep-alive',
+      'host': serverHost,
+    },
+  });
+
+  logs.splice(0, logs.length);
+}
+
+// NODE_USE_ENV_PROXY=0 and --no-use-env-proxy can be used at the same time.
+{
+  const { code, signal, stderr, stdout } = await runProxiedRequest({
+    NODE_USE_ENV_PROXY: '0',
+    REQUEST_URL: requestUrl,
+    HTTP_PROXY: `http://localhost:${proxy.address().port}`,
+  }, ['--no-use-env-proxy']);
+
+  assert.strictEqual(stderr.trim(), '');
+  assert.match(stdout, /Hello world/);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(signal, null);
+
+  // Should NOT use the proxy
+  assert.strictEqual(logs.length, 0);
+}
+
+// --use-env-proxy CLI flag takes precedence over NODE_USE_ENV_PROXY=0.
+{
+  const { code, signal, stderr, stdout } = await runProxiedRequest({
+    NODE_USE_ENV_PROXY: '0',
+    REQUEST_URL: requestUrl,
+    HTTP_PROXY: `http://localhost:${proxy.address().port}`,
+  }, ['--use-env-proxy']);
+
+  assert.strictEqual(stderr.trim(), '');
+  assert.match(stdout, /Hello world/);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(signal, null);
+
+  // Should use the proxy because CLI flag takes precedence
+  assert.strictEqual(logs.length, 1);
+  assert.deepStrictEqual(logs[0], {
+    method: 'GET',
+    url: requestUrl,
+    headers: {
+      'connection': 'keep-alive',
+      'proxy-connection': 'keep-alive',
+      'host': serverHost,
+    },
+  });
+
+  logs.splice(0, logs.length);
+}
+
+// --no-use-env-proxy CLI flag disables the proxy even if NODE_USE_ENV_PROXY=1.
+{
+  const { code, signal, stderr, stdout } = await runProxiedRequest({
+    NODE_USE_ENV_PROXY: '1',
+    REQUEST_URL: requestUrl,
+    HTTP_PROXY: `http://localhost:${proxy.address().port}`,
+  }, ['--no-use-env-proxy']);
+
+  // Should NOT use the proxy because CLI flag takes precedence.
+  assert.strictEqual(stderr.trim(), '');
+  assert.match(stdout, /Hello world/);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(signal, null);
+  assert.strictEqual(logs.length, 0);
+}
+
+proxy.close();
+server.close();
diff --git a/test/common/proxy-server.js b/test/common/proxy-server.js
index def986d19dd9f3..29a4073e13467a 100644
--- a/test/common/proxy-server.js
+++ b/test/common/proxy-server.js
@@ -142,11 +142,11 @@ function spawnPromisified(...args) {
   });
 }
 
-exports.checkProxiedFetch = async function(envExtension, expectation) {
+exports.checkProxiedFetch = async function(envExtension, expectation, cliArgsExtension = []) {
   const fixtures = require('./fixtures');
   const { code, signal, stdout, stderr } = await spawnPromisified(
     process.execPath,
-    [fixtures.path('fetch-and-log.mjs')], {
+    [...cliArgsExtension, fixtures.path('fetch-and-log.mjs')], {
       env: {
         ...process.env,
         ...envExtension,
@@ -166,11 +166,11 @@ exports.checkProxiedFetch = async function(envExtension, expectation) {
   });
 };
 
-exports.runProxiedRequest = async function(envExtension) {
+exports.runProxiedRequest = async function(envExtension, cliArgsExtension = []) {
   const fixtures = require('./fixtures');
   return spawnPromisified(
     process.execPath,
-    [fixtures.path('request-and-log.js')], {
+    [...cliArgsExtension, fixtures.path('request-and-log.js')], {
       env: {
         ...process.env,
         ...envExtension,

From ff67a4d9b5b102a4bb780322a350e995d16eb83f Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Fri, 25 Jul 2025 17:31:04 +0200
Subject: [PATCH 2/2] fixup! cli: add --use-env-proxy

---
 doc/api/cli.md                        | 5 ++---
 lib/internal/process/pre_execution.js | 6 +++---
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 38192350b4c308..ca6e0e684ed6fd 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -3012,6 +3012,7 @@ environment variables during startup, and tunnels requests over the
 specified proxy.
 
 This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
+When both are set, `--use-env-proxy` takes precedence.
 
 ### `--use-largepages=mode`
 
@@ -3669,9 +3670,7 @@ environment variables during startup, and tunnels requests over the
 specified proxy.
 
 This can also be enabled using the [`--use-env-proxy`][] command-line flag.
-
-This currently only affects requests sent over `fetch()`. Support for other
-built-in `http` and `https` methods is under way.
+When both are set, `--use-env-proxy` takes precedence.
 
 ### `NODE_V8_COVERAGE=dir`
 
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
index 139a66a6d0e508..480e150496d2db 100644
--- a/lib/internal/process/pre_execution.js
+++ b/lib/internal/process/pre_execution.js
@@ -181,9 +181,9 @@ function setupHttpProxy() {
   // For fetch, we need to set the global dispatcher from here.
   // For http/https agents, we'll configure the global agent when they are
   // actually created, in lib/_http_agent.js and lib/https.js.
-  // TODO(joyeecheung): This is currently guarded with NODE_USE_ENV_PROXY. Investigate whether
-  // it's possible to enable it by default without stepping on other existing libraries that
-  // sets the global dispatcher or monkey patches the global agent.
+  // TODO(joyeecheung): This is currently guarded with NODE_USE_ENV_PROXY and --use-env-proxy.
+  // Investigate whether it's possible to enable it by default without stepping on other
+  // existing libraries that sets the global dispatcher or monkey patches the global agent.
 }
 
 function setupUserModules(forceDefaultLoader = false) {