How auth0-deploy-cli Implements HTTP Proxy Support with Undici

Auth0-deploy-cli routes all HTTP traffic through a proxy by setting the HTTP_PROXY environment variable and registering Undici's ProxyAgent as the global dispatcher when the --proxy_url flag is provided.

Corporate networks and secure environments often require outbound HTTP traffic to pass through proxies. The auth0-deploy-cli handles this requirement by integrating Undici, Node.js's high-performance HTTP client, and configuring it at the application entry point. This design ensures that all requests to the Auth0 Management API—including exports, imports, and configuration deployments—respect the specified proxy without requiring changes to individual API calls.

How Proxy Support Works in auth0-deploy-cli

The implementation follows a minimal, centralized approach. Rather than modifying every HTTP request throughout the codebase, the CLI sets up proxy routing once during initialization.

CLI Argument Definition

The proxy configuration surface is defined in src/args.ts (lines 42–46), where the --proxy_url (short form -p) argument is declared. This allows users to specify the proxy endpoint directly from the command line.

Entry Point Configuration

In src/index.ts, the entry point extracts the flag value from parsed parameters:

const proxy = params.proxy_url;

This value is then processed through a series of setup steps that validate the environment and configure the HTTP layer.

Node Version Guard

Before configuring the proxy, the code validates the Node.js runtime version (lines 21–25). The proxy support requires Node.js 10 or higher. If the runtime check fails, the CLI throws an informative error and exits early, preventing undefined behavior in older environments.

Undici Global Dispatcher Setup

The critical implementation detail occurs when a proxy URL is present. The code performs two actions:

1. Environment Variable Assignment: The proxy URL is assigned to process.env.HTTP_PROXY (line 27), ensuring compatibility with downstream libraries that respect standard proxy environment variables.

2. Global Dispatcher Registration: The CLI imports ProxyAgent from Undici (line 4) and calls setGlobalDispatcher(new ProxyAgent(process.env.HTTP_PROXY)) (lines 31–32). This configures Undici to route all HTTP requests through the specified proxy endpoint.

Because the Auth0 Node.js SDK (v4.x) uses Undici as its HTTP transport layer, setting the global dispatcher is sufficient to proxy every Management API request without modifying individual client configurations.

Code Implementation Details

The proxy initialization logic in src/index.ts demonstrates the complete flow:

import { setGlobalDispatcher, ProxyAgent } from 'undici';

// ... argument parsing ...

const proxy = params.proxy_url;

// Node version validation (lines 21-25)
if (nodeVersion < 10) {
  throw new Error('Node.js version >= 10 is required for proxy support');
}

if (proxy) {
  process.env.HTTP_PROXY = proxy;                    // Line 27
  setGlobalDispatcher(new ProxyAgent(proxy));        // Lines 31-32
}

This approach isolates network topology concerns to the entry point, keeping the rest of the codebase—including the export and import command implementations—agnostic to whether traffic routes through a proxy or connects directly.

Usage Examples

Command Line Usage

Export an Auth0 tenant configuration through a corporate proxy:

auth0-deploy export \
  --config_file config.json \
  --format yaml \
  --output_folder ./export \
  --proxy_url http://proxy.mycompany.com:8080

Programmatic Usage

When using auth0-deploy-cli as a library, configure the proxy before invoking commands:

import { setGlobalDispatcher, ProxyAgent } from 'undici';
import cli from 'auth0-deploy-cli';

// Configure proxy before any HTTP requests occur
process.env.HTTP_PROXY = 'http://proxy.mycompany.com:8080';
setGlobalDispatcher(new ProxyAgent(process.env.HTTP_PROXY));

// Execute deployment commands
await cli.export({
  config_file: 'config.json',
  format: 'yaml',
  output_folder: './export'
});

Summary

• Centralized Configuration: Proxy support is configured once in src/index.ts using Undici's setGlobalDispatcher, affecting all subsequent HTTP requests.
• CLI Integration: The --proxy_url flag in src/args.ts provides the user interface for specifying proxy endpoints.
• Environment Compatibility: The implementation sets HTTP_PROXY to ensure compatibility with other libraries while primarily leveraging Undici's ProxyAgent.
• Version Requirements: Node.js 10 or higher is required for proxy functionality, enforced at runtime.
• SDK Transparency: Because the Auth0 Management API client uses Undici, no additional configuration is needed at the SDK level to enable proxy support.

Frequently Asked Questions

What Node.js version is required for proxy support?

Auth0-deploy-cli requires Node.js 10 or higher to use the HTTP proxy functionality. The code explicitly checks the runtime version in src/index.ts (lines 21–25) and throws an error if running on an unsupported version, as Undici's ProxyAgent relies on APIs introduced in later Node.js releases.

Does auth0-deploy-cli support authenticated proxies?

Yes. The --proxy_url parameter accepts standard URL formats including credentials. You can pass authentication details within the URL itself (e.g., http://username:password@proxy.company.com:8080), which Undici's ProxyAgent parses and uses for proxy authentication headers.

Will this proxy configuration affect all Auth0 API calls?

Yes. By calling setGlobalDispatcher with a ProxyAgent instance, the configuration affects all HTTP requests made through Undici throughout the application lifecycle. This includes every call to the Auth0 Management API made by the internal SDK client, ensuring consistent routing for export, import, and deployment operations.

Can I use the HTTP_PROXY environment variable instead of the CLI flag?

Yes. While the CLI provides the --proxy_url convenience flag, the code assigns this value to process.env.HTTP_PROXY (line 27 in src/index.ts). If you set HTTP_PROXY in your environment before running the CLI, you would need to manually configure Undici's global dispatcher, as the CLI only initializes the ProxyAgent when the --proxy_url flag is explicitly provided.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}