Documentation

#Installation

TunnelFlow's CLI is a single npm package. Install it globally:

npm install -g tunnelflow

Requirements: Node.js 18+ and npm. Works on macOS, Linux, and Windows.

After installing, verify it works:

tflow --version

#Authentication

Sign in to tunnelflow.dev with your GitHub account. Copy your auth token from the dashboard and save it to the CLI:

tflow login YOUR_AUTH_TOKEN

Your token is stored in ~/.tflow/config.json. You can also pass it per-command with --token.

To check your current auth status:

tflow status

To sign out and remove the saved token:

tflow logout

#Quick Start

Start your local dev server (e.g. on port 3000), then expose it:

tflow connect 3000

TunnelFlow creates a secure HTTPS tunnel and gives you a public URL like https://a3f9b1c2.tunnelflow.dev. All HTTP traffic to that URL is forwarded to your localhost:3000 in real time.

You'll see live traffic in the terminal as requests come in:

✓ Tunnel established
  Forwarding  https://a3f9b1c2.tunnelflow.dev → localhost:3000

  GET    /           200 (34ms)
  POST   /webhook    201 (12ms)
  PUT    /api/users  200 (8ms)

#Tunnelling

The core of TunnelFlow. Expose any local port to the internet over a secure HTTPS connection with auto-renewing wildcard TLS certificates.

tflow connect <port>

Options:

• •-t, --token <token> — Override saved auth token
• •-s, --subdomain <name> — Request a custom subdomain (Pro)
• •--server <url> — Custom tunnel server URL

The tunnel stays open as long as the CLI is running. Press Ctrl+C to disconnect.

#File Sharing

Share any file or folder directly from your machine — no uploads, no cloud storage. TunnelFlow serves it via a built-in file server.

tflow share ./my-folder

This creates a tunnel that serves the file or directory with a clean file browser UI. Share the generated URL with anyone.

Supports the same --subdomain and --token options as tflow connect.

#Custom Subdomains

Free users get a random subdomain (e.g. a3f9b1c2.tunnelflow.dev) that changes on each reconnect.

Pro users can reserve a persistent custom subdomain that stays the same across sessions:

tflow connect 3000 --subdomain my-api

This gives you https://my-api.tunnelflow.dev — a stable URL you can share with clients, put in webhook configs, or add to CI pipelines.

#Auto-Reconnect

If your connection drops (laptop sleeps, Wi-Fi hiccup), TunnelFlow automatically reconnects and restores your subdomain within a 60-second grace window. No action needed — the CLI handles it.

You'll see a reconnecting message in the terminal, and once restored the same URL continues working.

#Traffic InspectorPro

A real-time feed of every HTTP request and response passing through your tunnel. Available in the dashboard under the Inspector tab.

For each request you can see:

• •Method, path, query string, and status code
• •Full request and response headers
• •Request and response body (base64-decoded, with JSON pretty-printing)
• •Latency in milliseconds
• •Timestamp

Request Replay

Click any request in the inspector and hit Replay to re-send the exact same request to your tunnel. Useful for retesting a webhook or reproducing a failed request without triggering the original source.

Filtering

Filter the traffic list by HTTP method (GET, POST, PUT, etc.) and status code range (2xx, 4xx, 5xx) using the dropdowns at the top of the inspector.

#Request BreakpointsPro

Intercept incoming HTTP requests before they reach your local server. Like a debugger breakpoint, but for network traffic.

How to use

1. Go to the Breakpoints tab in your dashboard
2. Select a tunnel from the dropdown and toggle breakpoints ON
3. Any incoming request now pauses instead of being forwarded
4. Click a paused request to inspect its headers and body
5. Edit headers or body if needed
6. Click Release to forward (with your edits) or Drop to reject it

Paused requests auto-timeout after 2 minutes if not acted on. The breakpoint panel polls every second so you see new requests instantly.

Use cases

• •Debug webhook payloads by inspecting them before your handler sees them
• •Test how your app handles modified headers (auth tokens, content types)
• •Manually approve/reject requests during sensitive testing

#Webhook SimulatorPro

Fire realistic webhook payloads at your tunnel without triggering real events. Accessible from the Tools button inside the Inspector tab.

Supported providers

Payload signing

Enter your webhook signing secret and TunnelFlow computes the correct HMAC signature for each provider:

• •Stripe — stripe-signature header with t=timestamp,v1=hmac
• •GitHub — x-hub-signature-256 header with sha256=hmac
• •Shopify — x-shopify-hmac-sha256 header
• •Slack — x-slack-signature header with v0=hmac

This means your webhook verification code works exactly as it would in production.

#Record & Replay SessionsPro

Record a sequence of HTTP requests passing through your tunnel, then replay the entire sequence later with original timing.

From the Dashboard

1. Open the Tools panel in the Inspector tab
2. Give your session a name (optional) and click Record
3. Use your app normally — all traffic is being captured
4. Click Stop when done
5. Your session appears in the list with request count and date
6. Click Replay to fire the same requests with the same timing

From the CLI

Replay a saved session by ID:

tflow replay 42

This calls the server which fires each recorded request sequentially with the original delays between them.

Use cases

• •Reproduce a multi-step bug flow exactly as it happened
• •Run regression tests by replaying a known-good session after code changes
• •Demo a user workflow to a colleague without manually clicking through it

#tflow inspect — Live TUI Traffic ViewerPro

A full-screen terminal UI that shows real-time traffic across all your active tunnels. No browser needed — works over SSH too.

tflow inspect

Keyboard shortcuts

The table shows time, method, path, status code, and latency for every request. New events push to the top in real time. The currently selected row is highlighted.

#Multi-Port RoutingPro

Route different URL paths on a single public tunnel URL to different local ports. For example, serve your frontend on port 3000 and your API on port 3001 through one subdomain.

Setup

1. Go to the Rules tab in the dashboard
2. Add a new rule with type Route to Port
3. Set the path pattern (e.g. /api/*) and target port (e.g. 3001)
4. Connect multiple CLI instances to the same subdomain with different ports:

# Terminal 1 — frontend
tflow connect 3000 --subdomain myapp

# Terminal 2 — API
tflow connect 3001 --subdomain myapp

# Terminal 3 — admin panel
tflow connect 3002 --subdomain myapp

Now https://myapp.tunnelflow.dev/api/* goes to port 3001, and everything else goes to port 3000 (the default). Add as many route rules as you need.

#Live Watch LinksPro

Generate a shareable, read-only URL that lets anyone watch your tunnel traffic live in their browser — no TunnelFlow account required.

From the Dashboard

Click the eye icon next to any tunnel in the Tunnels tab. A watch link is generated and copied to your clipboard.

From the CLI

tflow watch-link --subdomain myapp

This prints the watch URL and a QR code you can scan with a phone.

How it works

• •The link opens a public page at tunnelflow.dev/watch/TOKEN
• •No login required — anyone with the link can view
• •Shows a real-time feed of method, path, status, and latency
• •Links auto-expire after 24 hours
• •You can revoke a link early from the dashboard

Use cases

• •Pair debugging — share with a colleague so they see what you see
• •Live demos — show clients real traffic flowing through your API
• •Support calls — let support engineers observe your traffic without granting dashboard access

#Traffic DiffingPro

Compare any two requests in the Inspector side by side to see exactly what changed.

How to use

1. In the Inspector, check the box next to two requests you want to compare
2. A Diff button appears in the controls bar
3. Click it to open the diff modal

The diff view shows:

• •Request headers — added (green), removed (red), changed (yellow)
• •Request body — line-by-line diff with color highlighting
• •Response headers — same color-coded comparison
• •Response body — side-by-side with changes highlighted

JSON bodies are automatically pretty-printed before diffing for cleaner comparisons.

#Auto-Mock ModePro

Record real API responses and serve them as mocks — no backend server needed.

Learn Mode

Proxy traffic to your real server while recording every request/response pair:

tflow mock --learn 3000

This creates a tunnel, forwards all traffic to localhost:3000, and saves each response to ~/.tflow/mocks/SUBDOMAIN.json. You'll see LEARNED next to each request in the terminal output.

Serve Mode

Serve the recorded mocks without any backend:

tflow mock

TunnelFlow starts a local mock server, matches incoming requests against your mock file, and returns the recorded responses. Matching priority:

1. Exact match on method + path
2. Glob/wildcard match (e.g. /api/users/123 matches /api/users/*)
3. 404 fallback if no match

Other commands

Use cases

• •Frontend development without running the backend
• •Offline demos — serve a realistic API anywhere
• •Integration testing with deterministic, recorded responses

#AnalyticsPro

Hourly charts and aggregate metrics for your tunnel traffic. Available in the Analytics tab.

Metrics tracked:

• •Request volume — total requests per hour
• •Error rate — percentage of 4xx/5xx responses
• •Average latency — mean response time in ms

Time ranges: 1 hour, 24 hours, or 7 days. Data is aggregated per subdomain.

#Rules EnginePro

Configure traffic rules per tunnel from the Rules tab. Rules apply instantly — no CLI restart needed.

Each rule has a method filter (GET, POST, etc.) and a path pattern (e.g. /api/*). Available rule types:

Rules are evaluated in priority order (drag to reorder). The first matching rule wins. If no rule matches, the request is forwarded normally to your local server.

#Team CollaborationPro

Create a team workspace and invite colleagues. Team members can:

• •View all active tunnels in the shared dashboard
• •Inspect traffic on shared tunnels
• •Access analytics and rules for shared tunnels

Each team member has their own account and login. The team owner manages membership and can share specific tunnels with the team via the Team tab.

#CLI Reference

Complete list of all CLI commands:

Global options

#Plans & Limits