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

> Learn how auth0-deploy-cli implements HTTP proxy support with Undici by setting the HTTP_PROXY environment variable and registering Undici'sProxyAgent.

- Repository: [Auth0/auth0-deploy-cli](https://github.com/auth0/auth0-deploy-cli)
- Tags: internals
- Published: 2026-02-25

---

**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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/index.ts), the entry point extracts the flag value from parsed parameters:

```javascript
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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/index.ts) demonstrates the complete flow:

```javascript
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:

```bash
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:

```javascript
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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/index.ts) using Undici's `setGlobalDispatcher`, affecting all subsequent HTTP requests.
- **CLI Integration**: The `--proxy_url` flag in [`src/args.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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.