@cvasingh/httpsurl

CLI tool to expose local HTTP servers to the internet via secure HTTPS tunnels at httpsurl.in.

Published on npm as @cvasingh/httpsurl.

Installation

npm install -g @cvasingh/httpsurl

Both hsurl and httpsurl commands are available after install.

Command Reference

| Command | Aliases | Description | |---------|---------|-------------| | hsurl -v | -V, --version | Show version | | hsurl -h | --help | Show help | | hsurl login | signin, auth | Authenticate via browser | | hsurl login --token <t> | | Set token directly | | hsurl logout | signout | Remove saved credentials | | hsurl http <port> | live, start, tunnel, expose, serve | Create a tunnel | | hsurl http <port> -s <url> | | Custom server URL | | hsurl status | info | Show authentication status | | hsurl whoami | me | Print current user ID |

Quick Start

# 1. Login
hsurl login

# 2. Start a local server
npx http-server -p 8080

# 3. Expose it
hsurl live 8080

Your server is now accessible at https://<tunnelId>.httpsurl.in.

Usage

Login

# Opens browser for Clerk authentication + CLI token exchange
hsurl login

# Or provide a CLI token directly
hsurl login --token <cli-token>

# Aliases
hsurl signin
hsurl auth

The login flow:

1. CLI starts a temporary localhost HTTP server
2. Opens browser to https://httpsurl.in/cli-auth?callback=http://localhost:PORT
3. You sign in via Clerk in the browser
4. The browser exchanges the Clerk JWT for a long-lived CLI token via POST /api/cli-token
5. The CLI token (cli_<userId>_<hash>) is redirected back to the CLI callback
6. Token is saved to ~/.httpsurl/credentials.json (chmod 600)

Create a Tunnel

# Expose local port 3000
hsurl http 3000
hsurl live 3000
hsurl start 3000
hsurl tunnel 3000
hsurl expose 3000
hsurl serve 3000

# Custom server URL (for local development)
hsurl http 8080 --server ws://localhost:3000/connect

Output:

i Connecting to wss://httpsurl.in/connect...
i Connected, registering tunnel...
v Tunnel registered!

  httpsurl.in
  -----------------------------
  > Forwarding: https://abc123def456.httpsurl.in
  -----------------------------

> GET     /            200 12ms
> POST    /api/data    201 45ms
> GET     /style.css   200  3ms

Account

# Check auth status
hsurl status
hsurl info

# Print user ID
hsurl whoami
hsurl me

# Logout
hsurl logout
hsurl signout

Modules

cli.js -- Commander CLI

Commands with aliases:

• login (signin, auth) -- Opens browser to Clerk sign-in, exchanges JWT for CLI token
• http (live, start, tunnel, expose, serve) -- Creates tunnel with --server option
• status (info) -- Shows authentication status and credentials path
• whoami (me) -- Prints current user ID
• logout (signout) -- Removes saved credentials

tunnel-client.js -- WebSocket Client

• Connects to server, sends register message with CLI token
• Receives registered with tunnel URL
• Handles request messages by proxying to local server via local-proxy.js
• Sends response or response_error back
• Auto-reconnects with exponential backoff on disconnect
• Preserves tunnel ID across reconnections (within 60s grace period)

local-proxy.js -- HTTP Proxy

• Makes HTTP requests to 127.0.0.1:<port>
• Strips host and x-tunnel-host headers
• Base64 encodes/decodes request and response bodies
• 30s timeout per request

reconnect.js -- Exponential Backoff

• Initial delay: 1s
• Doubles each attempt: 1s -> 2s -> 4s -> 8s -> 16s -> 30s (max)
• Resets on successful reconnection
• Cancellable

logger.js -- Terminal Output

Colored output using chalk:

• info -- blue
• success -- green
• warn -- yellow
• error -- red
• request -- method-colored badges with status code and latency
• banner -- formatted tunnel URL display

protocol.js -- Message Constants

Shared message type constants (duplicated from server for simplicity):

• MSG_REGISTER, MSG_RESPONSE, MSG_RESPONSE_ERROR
• MSG_REGISTERED, MSG_REQUEST, MSG_ERROR

Dependencies

| Package | Purpose | |---------|---------| | ws | WebSocket client | | commander | CLI argument parsing | | chalk (v4, CJS) | Terminal colors | | nanoid (v3, CJS) | Request ID generation | | open (v8) | Open browser for login |