localpreview

Node CLI for opening an ephemeral LocalPreview session from a local development server to a public URL.

Usage

localpreview connect 3000
localpreview connect https://localhost:3000
localpreview connect 3000 --name my-app
localpreview connect 3000 -l
localpreview connect 5173 --capture localhost:4000

localpreview <target> is still accepted as a deprecated compatibility alias and prints a warning. New usage should prefer localpreview connect <target>.

Targets are parsed by @localpreview/protocol:

• 4000 means http://127.0.0.1:4000.
• URLs must use http or https.
• URL targets must include an explicit port.

Run localpreview -h for public help. When LOCALPREVIEW_ADMIN_TOKEN is set in the environment, global help also lists admin commands.

Admin commands

Subdomain cleanup is an admin-only operation. Export LOCALPREVIEW_ADMIN_TOKEN before running clean:

export LOCALPREVIEW_ADMIN_TOKEN=your-token
localpreview clean my-app --force
localpreview clean --all --force -l

Admin authorization is read from the environment only.

localpreview clean -h and localpreview list -h show full admin help only when LOCALPREVIEW_ADMIN_TOKEN is set. Without it, you get public help plus a note that admin commands require the variable.

Inspect active tunnels, Redis inventory drift, and sandbox leftovers without printing tokens or preview URLs:

localpreview list
localpreview list --limit 20 --skip 20 -l

The list view prints a compact summary, page details, and a practical table with subdomain, short tunnel/sandbox ids, age, relay health, sandbox status, and the control-plane note for each row.

Runtime Flow

1. The CLI validates the target and optional --name.
2. It calls the control-plane POST /api/tunnels.
3. The control-plane returns the public URL, relay WebSocket URL, tunnel id, and client token.
4. The CLI connects to the relay over WebSocket.
5. Browser requests flow through:

browser -> control-plane -> relay -> CLI WebSocket -> local target

6. When the process exits or receives SIGINT/SIGTERM, the CLI closes the relay connection and sends DELETE /api/tunnels/:id as best-effort cleanup.

Implementation Shape

The package is structured as small Effect-backed services:

• src/command.ts: command parsing, legacy alias handling, and top-level flow.
• src/cli-ui.ts: help text, terminal styling, and log formatting.
• src/config.ts: runtime defaults and environment-derived limits.
• src/control-plane.ts: tunnel create/delete HTTP adapter.
• src/relay-client.ts: WebSocket lifecycle, signals, and relay event handling.
• src/local-proxy.ts: relay message handling and local HTTP forwarding.
• src/errors.ts: typed CLI failure model.

ws remains the low-level WebSocket adapter. Promise/event APIs are kept at the edges; lifecycle, cleanup, concurrency, config, and typed failures are modeled in Effect.

Defaults and Limits

• Control-plane URL precedence: -l / --local (shorthand for --control-plane http://localhost:3000) > https://localpreview.dev
• Request body limit: 10 MB
• Response body limit: 50 MB
• Local request timeout: 30 seconds
• Max in-flight requests: 100
• Response chunks sent to relay: 64 KiB
• Initial relay connect retry budget: 10 seconds

Optional environment overrides:

LOCALPREVIEW_ADMIN_TOKEN=...          # required for `clean` and `list`
LOCALPREVIEW_REQUEST_BODY_LIMIT_BYTES=10485760
LOCALPREVIEW_RESPONSE_BODY_LIMIT_BYTES=52428800
LOCALPREVIEW_REQUEST_TIMEOUT_MS=30000
LOCALPREVIEW_MAX_IN_FLIGHT_REQUESTS=100
LOCALPREVIEW_RESPONSE_CHUNK_SIZE_BYTES=65536
LOCALPREVIEW_RELAY_CONNECT_TIMEOUT_MS=10000

Development

From the repo root:

pnpm --filter localpreview test
pnpm --filter localpreview typecheck
pnpm --filter localpreview build

To make the CLI available globally during local development:

pnpm --filter localpreview build
cd packages/cli
pnpm link --global

Then verify it from any directory:

which localpreview
localpreview connect 3000 -l

If pnpm reports that the global bin directory is missing, run pnpm setup, then restart the terminal so PNPM_HOME is added to PATH.

The global command points at dist/index.js, so rebuild after changing CLI source files.

For a local end-to-end run, start the relay and control-plane first:

pnpm dev:relay
pnpm dev:web
export LOCALPREVIEW_ADMIN_TOKEN=your-local-token
pnpm localpreview connect 3000 -l