portprism 2.0.3 → 2.0.5

package/README.md

@@ -0,0 +1,144 @@
+# PortPrism
+
+**Share your local dev server with anyone, instantly.** Point PortPrism at a local
+port and you get a clean, branded **HTTPS** URL that anyone can open in a browser — no
+account, no config, and nothing for your viewers to install.
+
+```bash
+npx portprism 3000
+```
+
+- 🔗 **Instant public URL** for any local HTTP server
+- 🖥️ **Branded viewer** — recipients see your app, not a tunnel warning page
+- 🔒 **TLS end-to-end**; optional password protection (Pro)
+- 🔁 **Auto-reconnect** — brief network drops recover on the same URL
+- 📱 **QR code** for quick mobile testing (`--qr`)
+- 🔎 **Request inspector** (`--inspect`) — a local ledger of tunnelled HTTP traffic for webhook/API debugging
+- 🤖 **MCP server** so AI agents can launch and manage tunnels
+- ⚙️ **`--json`** NDJSON output for scripts and CI
+
+> Requires **Node.js 18+**. Free links last 2 hours;
+> [PortPrism Pro](https://portprism.io/#pricing) adds persistent links, password
+> protection, custom subdomains, and analytics.
+
+---
+
+## Quick start
+
+Start your app (any stack, any port), then in a second terminal:
+
+```bash
+npx portprism 3000
+```
+
+```
+╭─────────────────────────────────────────────╮
+│  PortPrism · My App                          │
+│  Share URL   https://viewer.portprism.io/v/ab3k │
+│  Local       http://localhost:3000           │
+│  Expires     1h 59m                          │
+│  Status      ● Connected                     │
+╰─────────────────────────────────────────────╯
+```
+
+Send the `viewer.portprism.io/v/…` URL to anyone. Press `Ctrl+C` to stop.
+
+## Installation
+
+```bash
+# No install — always the latest (recommended)
+npx portprism <target>
+
+# Or install globally
+npm install -g portprism
+portprism <target>
+```
+
+## Usage
+
+```bash
+npx portprism [options] <target>
+```
+
+`<target>` is a **port** (forwarded to `localhost`) or a **`host:port`** pair:
+
+```bash
+npx portprism 3000                  # → localhost:3000
+npx portprism my-app.local:8080     # → custom host
+npx portprism 127.0.0.1:5000        # → specific address
+```
+
+### Options
+
+| Flag                    | Description                                                         |
+| ----------------------- | ------------------------------------------------------------------- |
+| `--name <label>`        | App name shown in the viewer and CLI box                            |
+| `--desc <text>`         | One-line description shown in the viewer                            |
+| `--password <pw>`       | Require a password to view the link _(Pro)_                         |
+| `--qr`                  | Print the share URL as a scannable QR code                          |
+| `--qr-invert`           | Swap the QR's black/white cells for light terminals                 |
+| `--json`                | Emit machine-readable NDJSON events instead of the box (scripts/CI) |
+| `--inspect`             | Serve a local request inspector at `http://localhost:4040`          |
+| `--inspect-port <port>` | Port for the request inspector (default `4040`)                     |
+| `--no-open`             | Don't auto-open the viewer URL in your browser                      |
+| `--no-screenshot`       | Skip the automatic preview screenshot                               |
+| `--relay <url>`         | Override the relay WebSocket URL (self-hosting)                     |
+| `--help`                | Show all options                                                    |
+
+### Account commands
+
+```bash
+portprism login       # sign in with a magic-link / one-time code
+portprism logout      # remove saved credentials
+portprism whoami      # show the current account and plan
+portprism upgrade     # open the Pro checkout in your browser
+portprism referral    # show your referral link for bonus tunnel-time
+portprism config      # open ~/.portprism/config.json in $EDITOR
+```
+
+## Request inspector (`--inspect`)
+
+Add `--inspect` to open a live, self-hosted traffic ledger at
+**`http://localhost:4040`** — every HTTP request forwarded through your tunnel is
+listed chronologically with its headers, query parameters, and decoded
+request/response bodies, updating live over Server-Sent Events. Ideal for debugging
+webhooks and API callbacks. It runs on Node's built-in HTTP server (no extra install)
+and keeps the last 200 requests in memory.
+
+## AI agents (MCP)
+
+PortPrism speaks the [Model Context Protocol](https://modelcontextprotocol.io):
+
+- **Local:** the [`portprism-mcp`](https://www.npmjs.com/package/portprism-mcp) stdio
+  server lets an agent `start_tunnel` / `stop_tunnel` / `list_tunnels` /
+  `get_tunnel_status`.
+- **Remote:** `https://mcp.portprism.io/mcp` lets web connectors manage your live
+  tunnels (Bearer-token auth).
+
+## Privacy & your data
+
+PortPrism is designed to move your app's traffic, not to read it.
+
+- **Encrypted end-to-end.** All traffic between the viewer's browser, the PortPrism
+  relay, and your machine travels over TLS (HTTPS / WSS).
+- **Transparent proxy.** The relay forwards bytes between the viewer and your local
+  app. It does **not** read, modify, or store the **content** of the requests and
+  responses passing through your tunnel — your application data never lands in our
+  database.
+- **What is stored** (for signed-in users): your email and auth token (for login),
+  session metadata (app name, token, expiry, view/request counts for Pro analytics),
+  and billing records via Stripe (we never see card numbers).
+- **Anonymous use:** free tunnels need no account. A one-way hashed device
+  fingerprint is used only to enforce the free-plan time quota.
+- **Links are public by default** — anyone with the URL can view your app. For
+  sensitive tools use `--password` (Pro) so only people with the password can open it.
+- **Consent:** on first run the CLI asks you to accept the Privacy Policy once (stored
+  in `~/.portprism/consent.json`). In `--json` mode it won't prompt — it exits with an
+  `error` event instead.
+
+Full policy: **<https://portprism.io/privacy-policy.html>**
+
+---
+
+Docs: **<https://portprism.io/install.html>** · FAQ:
+**<https://portprism.io/docs/faq.html>** · License: **MIT**