http-proxy-cli

2.1.0 verified Sat Apr 25 auth: no javascript

A command-line proxy tool that wraps the http-proxy library to provide simple HTTP/HTTPS request forwarding. Current stable version 2.1.0. Development appears slow with few releases. Key differentiator: zero-config CLI for quick proxy setups with route mapping, header injection, and host header preservation. Unlike full-featured proxies like mitmproxy or nginx, this is a lightweight, single-binary style tool for development and testing.

Common errors

error http-proxy: Permission denied ↓

cause Trying to bind to a port below 1024 without root/sudo.

fix

Use a port above 1024, e.g., http-proxy 8080

error Error: listen EADDRINUSE :::8000 ↓

cause Port 8000 already in use by another process.

fix

Kill the conflicting process or use a different port with --port.

Warnings

gotcha The --proxyHost option sets the Host header to the proxy target, which may cause issues with virtual hosting. ↓

fix Use --header 'Host: ...' manually if needed.

gotcha Route matching is simple string prefix-based; order of routes matters. Later routes override earlier ones? Actually first match wins. ↓

fix Place more specific routes earlier.

deprecated The http-proxy dependency is in maintenance mode; no new features. ↓

fix Consider alternatives like http-proxy-middleware or work with the underlying library directly.

Install

npm install http-proxy-cli

yarn add http-proxy-cli

pnpm add http-proxy-cli

Imports

http-proxy-cli (global command)

wrong

npm install http-proxy-cli (local) and using npx http-proxy or ./node_modules/.bin/http-proxy

correct

npm install -g http-proxy-cli && http-proxy --help

Primarily used as a global CLI tool; running locally requires npx or full path.

Quickstart

Forwards all HTTP requests to a local server on port 3000. Use in a separate terminal while running a Node.js app.

http-proxy 3000