portless 0.5.1 → 0.6.0

package/README.md

@@ -1,87 +1,100 @@
 # portless
 
-Replace port numbers with stable, named .localhost URLs. For humans and agents.
+Replace port numbers with stable, named .localhost URLs for local development. For humans and agents.
 
 ```diff
-- "dev": "next dev"              # http://localhost:3000
-+ "dev": "portless run next dev"   # http://myapp.localhost:1355
+- "dev": "next dev"                  # http://localhost:3000
++ "dev": "portless run next dev"     # https://myapp.localhost
 ```
 
-## Quick Start
+## Install
 
 ```bash
-# Install
 npm install -g portless
+```
+
+> Install globally. Do not add as a project dependency or run via npx.
+
+## Run your app
 
-# Run your app (auto-starts the proxy if needed)
-portless run next dev
-# -> http://<project>.localhost:1355
+```bash
+# Enable HTTPS (one-time setup, auto-generates certs)
+portless proxy start --https
 
-# Or specify a name explicitly
+portless myapp next dev
+# -> https://myapp.localhost
+
+# Without --https, runs on port 1355
 portless myapp next dev
 # -> http://myapp.localhost:1355
 ```
 
-> The proxy auto-starts when you run an app. You can also start it explicitly with `portless proxy start`.
-
-## Why
+The proxy auto-starts when you run an app. A random port (4000--4999) is assigned via the `PORT` environment variable. Most frameworks (Next.js, Express, Nuxt, etc.) respect this automatically. For frameworks that ignore `PORT` (Vite, Astro, React Router, Angular), portless auto-injects `--port` and `--host` flags.
 
-Local dev with port numbers is fragile:
+## Use in package.json
 
-- **Port conflicts** -- two projects default to the same port and you get `EADDRINUSE`
-- **Memorizing ports** -- was the API on 3001 or 8080?
-- **Refreshing shows the wrong app** -- stop one server, start another on the same port, and your open tab now shows something completely different
-- **Monorepo multiplier** -- every problem above scales with each service in the repo
-- **Agents test the wrong port** -- AI coding agents guess or hardcode the wrong port, especially in monorepos
-- **Cookie and storage clashes** -- cookies set on `localhost` bleed across apps on different ports; localStorage is lost when ports shift
-- **Hardcoded ports in config** -- CORS allowlists, OAuth redirect URIs, and `.env` files all break when ports change
-- **Sharing URLs with teammates** -- "what port is that on?" becomes a Slack question
-- **Browser history is useless** -- your history for `localhost:3000` is a jumble of unrelated projects
+```json
+{
+  "scripts": {
+    "dev": "portless run next dev"
+  }
+}
+```
 
-Portless fixes all of this by giving each dev server a stable, named `.localhost` URL that both humans and agents can rely on.
+## Subdomains
 
-## Usage
+Organize services with subdomains:
 
 ```bash
-# Auto-infer name from package.json / git / directory
-portless run next dev
-# -> http://<project>.localhost:1355
-
-# Explicit name
-portless myapp next dev
-# -> http://myapp.localhost:1355
-
-# Subdomains
 portless api.myapp pnpm start
 # -> http://api.myapp.localhost:1355
 
 portless docs.myapp next dev
 # -> http://docs.myapp.localhost:1355
+```
+
+Wildcard subdomain routing: any subdomain of a registered route routes to that app automatically (e.g. `tenant1.myapp.localhost:1355` routes to the `myapp` app without extra registration).
+
+## Git Worktrees
 
-# Wildcard subdomains (no extra registration needed)
-# Any subdomain of a registered route routes automatically:
-#   tenant1.myapp.localhost:1355  -> myapp
-#   tenant2.myapp.localhost:1355  -> myapp
+`portless run` automatically detects git worktrees. In a linked worktree, the branch name is prepended as a subdomain so each worktree gets its own URL without any config changes:
+
+```bash
+# Main worktree -- no prefix
+portless run next dev   # -> http://myapp.localhost:1355
+
+# Linked worktree on branch "fix-ui"
+portless run next dev   # -> http://fix-ui.myapp.localhost:1355
 ```
 
-### In package.json
+Use `--name` to override the inferred base name while keeping the worktree prefix:
 
-```json
-{
-  "scripts": {
-    "dev": "portless run next dev"
-  }
-}
+```bash
+portless run --name myapp next dev   # -> http://fix-ui.myapp.localhost:1355
 ```
 
-The proxy auto-starts when you run an app. Or start it explicitly: `portless proxy start`.
+Put `portless run` in your `package.json` once and it works everywhere -- the main checkout uses the plain name, each worktree gets a unique subdomain. No collisions, no `--force`.
+
+## Custom TLD
 
-## How It Works
+By default, portless uses `.localhost` which auto-resolves to `127.0.0.1` in most browsers. If you prefer a different TLD (e.g. `.test`), use `--tld`:
+
+```bash
+sudo portless proxy start --https --tld test
+portless myapp next dev
+# -> https://myapp.test
+```
+
+The proxy auto-syncs `/etc/hosts` for custom TLDs when started with sudo, so `.test` domains resolve correctly.
+
+Recommended: `.test` (IANA-reserved, no collision risk). Avoid `.local` (conflicts with mDNS/Bonjour) and `.dev` (Google-owned, forces HTTPS via HSTS).
+
+## How it works
 
 ```mermaid
 flowchart TD
     Browser["Browser\nmyapp.localhost:1355"]
-    Proxy["portless proxy<br>(port 1355)"]
+    Proxy["portless proxy\n(port 1355)"]
     App1[":4123\nmyapp"]
     App2[":4567\napi"]
 
@@ -94,8 +107,6 @@ flowchart TD
 2. **Run apps** -- `portless <name> <command>` assigns a free port and registers with the proxy
 3. **Access via URL** -- `http://<name>.localhost:1355` routes through the proxy to your app
 
-Apps are assigned a random port (4000-4999) via the `PORT` and `HOST` environment variables. Most frameworks (Next.js, Express, Nuxt, etc.) respect these automatically. For frameworks that ignore `PORT` (Vite, Astro, React Router, Angular, Expo, React Native), portless auto-injects the correct `--port` and `--host` flags.
-
 ## HTTP/2 + HTTPS
 
 Enable HTTP/2 for faster dev server page loads. Browsers limit HTTP/1.1 to 6 connections per host, which bottlenecks dev servers that serve many unbundled files (Vite, Nuxt, etc.). HTTP/2 multiplexes all requests over a single connection.
@@ -123,7 +134,7 @@ On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and
 ## Commands
 
 ```bash
-portless run <cmd> [args...]     # Infer name from project, run through proxy
+portless run [--name <name>] <cmd> [args...]  # Infer name (or override with --name), run through proxy
 portless <name> <cmd> [args...]  # Run app at http://<name>.localhost:1355
 portless alias <name> <port>     # Register a static route (e.g. for Docker)
 portless alias <name> <port> --force  # Overwrite an existing route
@@ -135,7 +146,6 @@ portless hosts clean             # Remove portless entries from /etc/hosts
 
 # Disable portless (run command directly)
 PORTLESS=0 pnpm dev              # Bypasses proxy, uses default port
-# Also accepts PORTLESS=skip
 
 # Proxy control
 portless proxy start             # Start the proxy (port 1355, daemon)
@@ -143,64 +153,42 @@ portless proxy start --https     # Start with HTTP/2 + TLS
 portless proxy start -p 80       # Start on port 80 (requires sudo)
 portless proxy start --foreground  # Start in foreground (for debugging)
 portless proxy stop              # Stop the proxy
-
-# Options
--p, --port <number>              # Port for the proxy (default: 1355)
-                                 # Ports < 1024 require sudo
---https                          # Enable HTTP/2 + TLS with auto-generated certs
---cert <path>                    # Use a custom TLS certificate (implies --https)
---key <path>                     # Use a custom TLS private key (implies --https)
---no-tls                         # Disable HTTPS (overrides PORTLESS_HTTPS)
---foreground                     # Run proxy in foreground instead of daemon
---app-port <number>              # Use a fixed port for the app (skip auto-assignment)
---force                          # Override a route registered by another process
---name <name>                    # Use <name> as the app name (bypasses subcommand dispatch)
---                               # Stop flag parsing; everything after is passed to the child
-
-# Injected into child processes
-PORT                             # Ephemeral port the child should listen on
-HOST                             # Always 127.0.0.1
-PORTLESS_URL                     # Public URL (e.g. http://myapp.localhost:1355)
-
-# Configuration
-PORTLESS_PORT=<number>           # Override the default proxy port
-PORTLESS_APP_PORT=<number>       # Use a fixed port for the app (same as --app-port)
-PORTLESS_HTTPS=1|true            # Always enable HTTPS
-PORTLESS_SYNC_HOSTS=1            # Auto-sync /etc/hosts when routes change
-PORTLESS_STATE_DIR=<path>        # Override the state directory
-
-# Info
-portless --help                  # Show help
-portless run --help              # Show help for a specific subcommand
-portless --version               # Show version
 ```
 
-> **Reserved names:** `run`, `alias`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run <cmd>` to infer the name from your project, or `portless --name <name> <cmd>` to force any name including reserved ones.
-
-## State Directory
-
-Portless stores its state (routes, PID file, port file) in a directory that depends on the proxy port:
+### Options
 
-- **Port < 1024** (sudo required): `/tmp/portless` -- shared between root and user processes
-- **Port >= 1024** (no sudo): `~/.portless` -- user-scoped, no root involvement
+```
+-p, --port <number>              Port for the proxy (default: 1355)
+--https                          Enable HTTP/2 + TLS with auto-generated certs
+--cert <path>                    Use a custom TLS certificate (implies --https)
+--key <path>                     Use a custom TLS private key (implies --https)
+--no-tls                         Disable HTTPS (overrides PORTLESS_HTTPS)
+--foreground                     Run proxy in foreground instead of daemon
+--tld <tld>                      Use a custom TLD instead of .localhost (e.g. test)
+--app-port <number>              Use a fixed port for the app (skip auto-assignment)
+--force                          Override a route registered by another process
+--name <name>                    Use <name> as the app name
+```
 
-Override with the `PORTLESS_STATE_DIR` environment variable if needed.
+### Environment variables
 
-## Development
-
-This repo is a pnpm workspace monorepo using [Turborepo](https://turbo.build). The publishable package lives in `packages/portless/`.
+```
+# Configuration
+PORTLESS_PORT=<number>           Override the default proxy port
+PORTLESS_APP_PORT=<number>       Use a fixed port for the app (same as --app-port)
+PORTLESS_HTTPS=1                 Always enable HTTPS
+PORTLESS_TLD=<tld>               Use a custom TLD (e.g. test; default: localhost)
+PORTLESS_SYNC_HOSTS=1            Auto-sync /etc/hosts (auto-enabled for custom TLDs)
+PORTLESS_STATE_DIR=<path>        Override the state directory
 
-```bash
-pnpm install          # Install all dependencies
-pnpm build            # Build all packages
-pnpm test             # Run tests
-pnpm test:coverage    # Run tests with coverage
-pnpm test:watch       # Run tests in watch mode
-pnpm lint             # Lint all packages
-pnpm typecheck        # Type-check all packages
-pnpm format           # Format all files with Prettier
+# Injected into child processes
+PORT                             Ephemeral port the child should listen on
+HOST                             Always 127.0.0.1
+PORTLESS_URL                     Public URL (e.g. https://myapp.localhost)
 ```
 
+> **Reserved names:** `run`, `alias`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run <cmd>` to infer the name from your project, or `portless --name <name> <cmd>` to force any name including reserved ones.
+
 ## Safari / DNS
 
 `.localhost` subdomains auto-resolve to `127.0.0.1` in Chrome, Firefox, and Edge. Safari relies on the system DNS resolver, which may not handle `.localhost` subdomains on all configurations.
@@ -208,23 +196,15 @@ pnpm format           # Format all files with Prettier
 If Safari can't find your `.localhost` URL:
 
 ```bash
-# Add current routes to /etc/hosts (requires sudo)
-sudo portless hosts sync
-
-# Clean up later
-sudo portless hosts clean
+sudo portless hosts sync    # Add current routes to /etc/hosts
+sudo portless hosts clean   # Clean up later
 ```
 
-To auto-sync `/etc/hosts` whenever routes change, set `PORTLESS_SYNC_HOSTS=1` and start the proxy with sudo:
-
-```bash
-export PORTLESS_SYNC_HOSTS=1
-sudo portless proxy start
-```
+Auto-syncs `/etc/hosts` for custom TLDs (e.g. `--tld test`). For `.localhost`, set `PORTLESS_SYNC_HOSTS=1` to enable. Disable with `PORTLESS_SYNC_HOSTS=0`.
 
 ## Proxying Between Portless Apps
 
-If your frontend dev server (e.g. Vite, webpack) proxies API requests to another portless app, make sure the proxy rewrites the `Host` header. Without this, the proxy sends the **original** Host header, causing portless to route the request back to the frontend in an infinite loop.
+If your frontend dev server (e.g. Vite, webpack) proxies API requests to another portless app, make sure the proxy rewrites the `Host` header. Without this, portless routes the request back to the frontend in an infinite loop.
 
 **Vite** (`vite.config.ts`):
 
@@ -233,7 +213,7 @@ server: {
   proxy: {
     "/api": {
       target: "http://api.myapp.localhost:1355",
-      changeOrigin: true,  // Required: rewrites Host header to match target
+      changeOrigin: true,
       ws: true,
     },
   },
@@ -247,13 +227,27 @@ devServer: {
   proxy: [{
     context: ["/api"],
     target: "http://api.myapp.localhost:1355",
-    changeOrigin: true,  // Required: rewrites Host header to match target
+    changeOrigin: true,
   }],
 }
 ```
 
 Portless detects this misconfiguration and responds with `508 Loop Detected` along with a message pointing to this fix.
 
+## Development
+
+This repo is a pnpm workspace monorepo using [Turborepo](https://turbo.build). The publishable package lives in `packages/portless/`.
+
+```bash
+pnpm install          # Install all dependencies
+pnpm build            # Build all packages
+pnpm test             # Run tests
+pnpm test:coverage    # Run tests with coverage
+pnpm lint             # Lint all packages
+pnpm typecheck        # Type-check all packages
+pnpm format           # Format all files with Prettier
+```
+
 ## Requirements
 
 - Node.js 20+

package/dist/{chunk-P3DHZHEZ.js → chunk-AB3HUERH.js}

@@ -22,15 +22,19 @@ function formatUrl(hostname, proxyPort, tls = false) {
   const defaultPort = tls ? 443 : 80;
   return proxyPort === defaultPort ? `${proto}://${hostname}` : `${proto}://${hostname}:${proxyPort}`;
 }
-function parseHostname(input) {
+function parseHostname(input, tld = "localhost") {
+  const suffix = `.${tld}`;
   let hostname = input.trim().replace(/^https?:\/\//, "").split("/")[0].toLowerCase();
-  if (!hostname || hostname === ".localhost") {
+  if (tld !== "localhost" && hostname.endsWith(".localhost")) {
+    hostname = hostname.slice(0, -".localhost".length);
+  }
+  if (!hostname || hostname === suffix) {
     throw new Error("Hostname cannot be empty");
   }
-  if (!hostname.endsWith(".localhost")) {
-    hostname = `${hostname}.localhost`;
+  if (!hostname.endsWith(suffix)) {
+    hostname = `${hostname}${suffix}`;
   }
-  const name = hostname.replace(/\.localhost$/, "");
+  const name = hostname.slice(0, -suffix.length);
   if (name.includes("..")) {
     throw new Error(`Invalid hostname "${name}": consecutive dots are not allowed`);
   }
@@ -39,6 +43,14 @@ function parseHostname(input) {
       `Invalid hostname "${name}": must contain only lowercase letters, digits, hyphens, and dots`
     );
   }
+  const labels = name.split(".");
+  for (const label of labels) {
+    if (label.length > 63) {
+      throw new Error(
+        `Invalid hostname "${name}": label "${label}" exceeds 63-character DNS limit`
+      );
+    }
+  }
   return hostname;
 }
 
@@ -291,7 +303,14 @@ function findRoute(routes, host) {
   return routes.find((r) => r.hostname === host) || routes.find((r) => host.endsWith("." + r.hostname));
 }
 function createProxyServer(options) {
-  const { getRoutes, proxyPort, onError = (msg) => console.error(msg), tls } = options;
+  const {
+    getRoutes,
+    proxyPort,
+    tld = "localhost",
+    onError = (msg) => console.error(msg),
+    tls
+  } = options;
+  const tldSuffix = `.${tld}`;
   const isTls = !!tls;
   const handleRequest = (req, res) => {
     res.setHeader(PORTLESS_HEADER, "1");
@@ -314,7 +333,7 @@ function createProxyServer(options) {
           "Loop Detected",
           `<div class="content"><p class="desc">This request has passed through portless ${hops} times. This usually means a dev server (Vite, webpack, etc.) is proxying requests back through portless without rewriting the Host header.</p><div class="section"><p class="label">Fix: add changeOrigin to your proxy config</p><pre class="terminal">proxy: {
   "/api": {
-    target: "http://&lt;backend&gt;.localhost:&lt;port&gt;",
+    target: "http://&lt;backend&gt;${escapeHtml(tldSuffix)}:&lt;port&gt;",
     changeOrigin: true,
   },
 }</pre></div></div>`
@@ -325,13 +344,15 @@ function createProxyServer(options) {
     const route = findRoute(routes, host);
     if (!route) {
       const safeHost = escapeHtml(host);
-      const routesList = routes.length > 0 ? `<div class="section"><p class="label">Active apps</p><ul class="card">${routes.map((r) => `<li><a href="${escapeHtml(formatUrl(r.hostname, proxyPort, isTls))}" class="card-link"><span class="name">${escapeHtml(r.hostname)}</span><span class="meta"><code class="port">localhost:${escapeHtml(String(r.port))}</code><span class="arrow">${ARROW_SVG}</span></span></a></li>`).join("")}</ul></div>` : '<p class="empty">No apps running.</p>';
+      const strippedHost = host.endsWith(tldSuffix) ? host.slice(0, -tldSuffix.length) : host;
+      const safeSuggestion = escapeHtml(strippedHost);
+      const routesList = routes.length > 0 ? `<div class="section"><p class="label">Active apps</p><ul class="card">${routes.map((r) => `<li><a href="${escapeHtml(formatUrl(r.hostname, proxyPort, isTls))}" class="card-link"><span class="name">${escapeHtml(r.hostname)}</span><span class="meta"><code class="port">127.0.0.1:${escapeHtml(String(r.port))}</code><span class="arrow">${ARROW_SVG}</span></span></a></li>`).join("")}</ul></div>` : '<p class="empty">No apps running.</p>';
       res.writeHead(404, { "Content-Type": "text/html" });
       res.end(
         renderPage(
           404,
           "Not Found",
-          `<div class="content"><p class="desc">No app registered for <strong>${safeHost}</strong></p>${routesList}<div class="section"><div class="terminal"><span class="prompt">$ </span>portless ${safeHost.replace(".localhost", "")} your-command</div></div></div>`
+          `<div class="content"><p class="desc">No app registered for <strong>${safeHost}</strong></p>${routesList}<div class="section"><div class="terminal"><span class="prompt">$ </span>portless ${safeSuggestion} your-command</div></div></div>`
         )
       );
       return;
@@ -587,7 +608,7 @@ function getManagedHostnames() {
     return parts.length >= 2 ? parts[1] : "";
   }).filter(Boolean);
 }
-function checkLocalhostResolution(hostname) {
+function checkHostResolution(hostname) {
   return new Promise((resolve) => {
     dns.lookup(hostname, { family: 4 }, (err, address) => {
       if (err) {
@@ -667,6 +688,54 @@ function writeTlsMarker(dir, enabled) {
     }
   }
 }
+var DEFAULT_TLD = "localhost";
+var RISKY_TLDS = /* @__PURE__ */ new Map([
+  ["local", "conflicts with mDNS/Bonjour on macOS"],
+  ["dev", "Google-owned; browsers force HTTPS via preloaded HSTS"],
+  ["com", "public TLD -- DNS requests will leak to the internet"],
+  ["org", "public TLD -- DNS requests will leak to the internet"],
+  ["net", "public TLD -- DNS requests will leak to the internet"],
+  ["io", "public TLD -- DNS requests will leak to the internet"],
+  ["app", "public TLD -- DNS requests will leak to the internet"],
+  ["edu", "public TLD -- DNS requests will leak to the internet"],
+  ["gov", "public TLD -- DNS requests will leak to the internet"],
+  ["mil", "public TLD -- DNS requests will leak to the internet"],
+  ["int", "public TLD -- DNS requests will leak to the internet"]
+]);
+function validateTld(tld) {
+  if (!tld) return "TLD cannot be empty";
+  if (!/^[a-z0-9]+$/.test(tld)) {
+    return `Invalid TLD "${tld}": must contain only lowercase letters and digits`;
+  }
+  return null;
+}
+var TLD_FILE = "proxy.tld";
+function readTldFromDir(dir) {
+  try {
+    const raw = fs3.readFileSync(path.join(dir, TLD_FILE), "utf-8").trim();
+    return raw || DEFAULT_TLD;
+  } catch {
+    return DEFAULT_TLD;
+  }
+}
+function writeTldFile(dir, tld) {
+  const filePath = path.join(dir, TLD_FILE);
+  if (tld === DEFAULT_TLD) {
+    try {
+      fs3.unlinkSync(filePath);
+    } catch {
+    }
+  } else {
+    fs3.writeFileSync(filePath, tld, { mode: 420 });
+  }
+}
+function getDefaultTld() {
+  const val = process.env.PORTLESS_TLD?.trim().toLowerCase();
+  if (!val) return DEFAULT_TLD;
+  const err = validateTld(val);
+  if (err) throw new Error(`PORTLESS_TLD: ${err}`);
+  return val;
+}
 function isHttpsEnvEnabled() {
   const val = process.env.PORTLESS_HTTPS;
   return val === "1" || val === "true";
@@ -676,24 +745,36 @@ async function discoverState() {
     const dir = process.env.PORTLESS_STATE_DIR;
     const port = readPortFromDir(dir) ?? getDefaultPort();
     const tls = readTlsMarker(dir);
-    return { dir, port, tls };
+    const tld = readTldFromDir(dir);
+    return { dir, port, tls, tld };
   }
   const userPort = readPortFromDir(USER_STATE_DIR);
   if (userPort !== null) {
-    const tls = readTlsMarker(USER_STATE_DIR);
-    if (await isProxyRunning(userPort, tls)) {
-      return { dir: USER_STATE_DIR, port: userPort, tls };
+    if (await isProxyRunning(userPort)) {
+      const tls = readTlsMarker(USER_STATE_DIR);
+      const tld = readTldFromDir(USER_STATE_DIR);
+      return { dir: USER_STATE_DIR, port: userPort, tls, tld };
     }
   }
   const systemPort = readPortFromDir(SYSTEM_STATE_DIR);
   if (systemPort !== null) {
-    const tls = readTlsMarker(SYSTEM_STATE_DIR);
-    if (await isProxyRunning(systemPort, tls)) {
-      return { dir: SYSTEM_STATE_DIR, port: systemPort, tls };
+    if (await isProxyRunning(systemPort)) {
+      const tls = readTlsMarker(SYSTEM_STATE_DIR);
+      const tld = readTldFromDir(SYSTEM_STATE_DIR);
+      return { dir: SYSTEM_STATE_DIR, port: systemPort, tls, tld };
     }
   }
   const defaultPort = getDefaultPort();
-  return { dir: resolveStateDir(defaultPort), port: defaultPort, tls: false };
+  const probePorts = /* @__PURE__ */ new Set([defaultPort, 443, 80]);
+  for (const port of probePorts) {
+    if (await isProxyRunning(port)) {
+      const dir = resolveStateDir(port);
+      const tls = readTlsMarker(dir);
+      const tld = readTldFromDir(dir);
+      return { dir, port, tls, tld };
+    }
+  }
+  return { dir: resolveStateDir(defaultPort), port: defaultPort, tls: false, tld: getDefaultTld() };
 }
 async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
   if (minPort > maxPort) {
@@ -1067,12 +1148,18 @@ export {
   syncHostsFile,
   cleanHostsFile,
   getManagedHostnames,
-  checkLocalhostResolution,
+  checkHostResolution,
   PRIVILEGED_PORT_THRESHOLD,
   getDefaultPort,
   resolveStateDir,
   readTlsMarker,
   writeTlsMarker,
+  DEFAULT_TLD,
+  RISKY_TLDS,
+  validateTld,
+  readTldFromDir,
+  writeTldFile,
+  getDefaultTld,
   isHttpsEnvEnabled,
   discoverState,
   findFreePort,

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import {
+  DEFAULT_TLD,
   FILE_MODE,
   PRIVILEGED_PORT_THRESHOLD,
+  RISKY_TLDS,
   RouteConflictError,
   RouteStore,
   cleanHostsFile,
@@ -12,19 +14,23 @@ import {
   fixOwnership,
   formatUrl,
   getDefaultPort,
+  getDefaultTld,
   injectFrameworkFlags,
   isErrnoException,
   isHttpsEnvEnabled,
   isProxyRunning,
   parseHostname,
   prompt,
+  readTldFromDir,
   readTlsMarker,
   resolveStateDir,
   spawnCommand,
   syncHostsFile,
+  validateTld,
   waitForProxy,
+  writeTldFile,
   writeTlsMarker
-} from "./chunk-P3DHZHEZ.js";
+} from "./chunk-AB3HUERH.js";
 
 // src/cli.ts
 import chalk from "chalk";
@@ -218,19 +224,24 @@ function isCATrusted(stateDir) {
 }
 function isCATrustedMacOS(caCertPath) {
   try {
-    const fingerprint = openssl(["x509", "-in", caCertPath, "-noout", "-fingerprint", "-sha1"]).trim().replace(/^.*=/, "").replace(/:/g, "").toLowerCase();
-    for (const keychain of [loginKeychainPath(), "/Library/Keychains/System.keychain"]) {
-      try {
-        const result = execFileSync("security", ["find-certificate", "-a", "-Z", keychain], {
-          encoding: "utf-8",
-          timeout: 5e3,
-          stdio: ["pipe", "pipe", "pipe"]
-        });
-        if (result.toLowerCase().includes(fingerprint)) return true;
-      } catch {
-      }
+    const isRoot = (process.getuid?.() ?? -1) === 0;
+    const sudoUser = process.env.SUDO_USER;
+    if (isRoot && sudoUser) {
+      execFileSync(
+        "sudo",
+        ["-u", sudoUser, "security", "verify-cert", "-c", caCertPath, "-L", "-p", "ssl"],
+        {
+          stdio: "pipe",
+          timeout: 5e3
+        }
+      );
+    } else {
+      execFileSync("security", ["verify-cert", "-c", caCertPath, "-L", "-p", "ssl"], {
+        stdio: "pipe",
+        timeout: 5e3
+      });
     }
-    return false;
+    return true;
   } catch {
     return false;
   }
@@ -364,12 +375,12 @@ async function generateHostCertAsync(stateDir, hostname) {
   fixOwnership(keyPath, certPath);
   return { certPath, keyPath };
 }
-function createSNICallback(stateDir, defaultCert, defaultKey) {
+function createSNICallback(stateDir, defaultCert, defaultKey, tld = "localhost") {
   const cache = /* @__PURE__ */ new Map();
   const pending = /* @__PURE__ */ new Map();
   const defaultCtx = tls.createSecureContext({ cert: defaultCert, key: defaultKey });
   return (servername, cb) => {
-    if (servername === "localhost") {
+    if (servername === tld) {
       cb(null, defaultCtx);
       return;
     }
@@ -422,12 +433,29 @@ function trustCA(stateDir) {
   }
   try {
     if (process.platform === "darwin") {
-      const keychain = loginKeychainPath();
-      execFileSync(
-        "security",
-        ["add-trusted-cert", "-r", "trustRoot", "-k", keychain, caCertPath],
-        { stdio: "pipe", timeout: 3e4 }
-      );
+      const isRoot = (process.getuid?.() ?? -1) === 0;
+      if (isRoot) {
+        execFileSync(
+          "security",
+          [
+            "add-trusted-cert",
+            "-d",
+            "-r",
+            "trustRoot",
+            "-k",
+            "/Library/Keychains/System.keychain",
+            caCertPath
+          ],
+          { stdio: "pipe", timeout: 3e4 }
+        );
+      } else {
+        const keychain = loginKeychainPath();
+        execFileSync(
+          "security",
+          ["add-trusted-cert", "-r", "trustRoot", "-k", keychain, caCertPath],
+          { stdio: "pipe", timeout: 3e4 }
+        );
+      }
       return { trusted: true };
     } else if (process.platform === "linux") {
       const config = getLinuxCATrustConfig();
@@ -453,11 +481,21 @@ function trustCA(stateDir) {
 }
 
 // src/auto.ts
+import { createHash } from "crypto";
 import { execFileSync as execFileSync2 } from "child_process";
 import * as fs2 from "fs";
 import * as path2 from "path";
+var MAX_DNS_LABEL_LENGTH = 63;
+function truncateLabel(label) {
+  if (label.length <= MAX_DNS_LABEL_LENGTH) return label;
+  const hash = createHash("sha256").update(label).digest("hex").slice(0, 6);
+  const maxPrefixLength = MAX_DNS_LABEL_LENGTH - 7;
+  const prefix = label.slice(0, maxPrefixLength).replace(/-+$/, "");
+  return `${prefix}-${hash}`;
+}
 function sanitizeForHostname(name) {
-  return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+  const sanitized = name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+  return truncateLabel(sanitized);
 }
 function inferProjectName(cwd = process.cwd()) {
   const pkgResult = findPackageJsonName(cwd);
@@ -602,7 +640,7 @@ var DEBOUNCE_MS = 100;
 var POLL_INTERVAL_MS = 3e3;
 var EXIT_TIMEOUT_MS = 2e3;
 var SUDO_SPAWN_TIMEOUT_MS = 3e4;
-function startProxyServer(store, proxyPort, tlsOptions) {
+function startProxyServer(store, proxyPort, tld, tlsOptions) {
   store.ensureDir();
   const isTls = !!tlsOptions;
   const routesPath = store.getRoutesPath();
@@ -618,7 +656,8 @@ function startProxyServer(store, proxyPort, tlsOptions) {
   let debounceTimer = null;
   let watcher = null;
   let pollingInterval = null;
-  const autoSyncHosts = process.env.PORTLESS_SYNC_HOSTS === "1";
+  const syncVal = process.env.PORTLESS_SYNC_HOSTS;
+  const autoSyncHosts = syncVal === "1" || syncVal === "true" || tld !== DEFAULT_TLD && syncVal !== "0" && syncVal !== "false";
   const reloadRoutes = () => {
     try {
       cachedRoutes = store.loadRoutes();
@@ -643,6 +682,7 @@ function startProxyServer(store, proxyPort, tlsOptions) {
   const server = createProxyServer({
     getRoutes: () => cachedRoutes,
     proxyPort,
+    tld,
     onError: (msg) => console.error(chalk.red(msg)),
     tls: tlsOptions
   });
@@ -668,9 +708,11 @@ function startProxyServer(store, proxyPort, tlsOptions) {
     fs3.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
     fs3.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
     writeTlsMarker(store.dir, isTls);
+    writeTldFile(store.dir, tld);
     fixOwnership(store.dir, store.pidPath, store.portFilePath);
     const proto = isTls ? "HTTPS/2" : "HTTP";
-    console.log(chalk.green(`${proto} proxy listening on port ${proxyPort}`));
+    const tldLabel = tld !== DEFAULT_TLD ? ` (TLD: .${tld})` : "";
+    console.log(chalk.green(`${proto} proxy listening on port ${proxyPort}${tldLabel}`));
   });
   let exiting = false;
   const cleanup = () => {
@@ -690,6 +732,7 @@ function startProxyServer(store, proxyPort, tlsOptions) {
     } catch {
     }
     writeTlsMarker(store.dir, false);
+    writeTldFile(store.dir, DEFAULT_TLD);
     if (autoSyncHosts) cleanHostsFile();
     server.close(() => process.exit(0));
     setTimeout(() => process.exit(0), EXIT_TIMEOUT_MS).unref();
@@ -699,12 +742,12 @@ function startProxyServer(store, proxyPort, tlsOptions) {
   console.log(chalk.cyan("\nProxy is running. Press Ctrl+C to stop.\n"));
   console.log(chalk.gray(`Routes file: ${store.getRoutesPath()}`));
 }
-async function stopProxy(store, proxyPort, tls2) {
+async function stopProxy(store, proxyPort, _tls) {
   const pidPath = store.pidPath;
   const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
   const sudoHint = needsSudo ? "sudo " : "";
   if (!fs3.existsSync(pidPath)) {
-    if (await isProxyRunning(proxyPort, tls2)) {
+    if (await isProxyRunning(proxyPort)) {
       console.log(chalk.yellow(`PID file is missing but port ${proxyPort} is still in use.`));
       const pid = findPidOnPort(proxyPort);
       if (pid !== null) {
@@ -759,7 +802,7 @@ async function stopProxy(store, proxyPort, tls2) {
       }
       return;
     }
-    if (!await isProxyRunning(proxyPort, tls2)) {
+    if (!await isProxyRunning(proxyPort)) {
       console.log(
         chalk.yellow(
           `PID file exists but port ${proxyPort} is not listening. The PID may have been recycled.`
@@ -806,8 +849,22 @@ function listRoutes(store, proxyPort, tls2) {
   }
   console.log();
 }
-async function runApp(store, proxyPort, stateDir, name, commandArgs, tls2, force, autoInfo, desiredPort) {
-  const hostname = parseHostname(name);
+async function runApp(store, proxyPort, stateDir, name, commandArgs, tls2, tld, force, autoInfo, desiredPort) {
+  const hostname = parseHostname(name, tld);
+  let envTld;
+  try {
+    envTld = getDefaultTld();
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+  if (envTld !== DEFAULT_TLD && envTld !== tld) {
+    console.warn(
+      chalk.yellow(
+        `Warning: PORTLESS_TLD=${envTld} but the running proxy uses .${tld}. Using .${tld}.`
+      )
+    );
+  }
   console.log(chalk.blue.bold(`
 portless
 `));
@@ -845,6 +902,7 @@ portless
       console.log(chalk.yellow("Starting proxy (requires sudo)..."));
       const startArgs = [process.execPath, process.argv[1], "proxy", "start"];
       if (wantHttps) startArgs.push("--https");
+      if (tld !== DEFAULT_TLD) startArgs.push("--tld", tld);
       const result = spawnSync("sudo", startArgs, {
         stdio: "inherit",
         timeout: SUDO_SPAWN_TIMEOUT_MS
@@ -859,6 +917,7 @@ portless
       console.log(chalk.yellow("Starting proxy..."));
       const startArgs = [process.argv[1], "proxy", "start"];
       if (wantHttps) startArgs.push("--https");
+      if (tld !== DEFAULT_TLD) startArgs.push("--tld", tld);
       const result = spawnSync(process.execPath, startArgs, {
         stdio: "inherit",
         timeout: SUDO_SPAWN_TIMEOUT_MS
@@ -871,6 +930,7 @@ portless
       }
     }
     const autoTls = readTlsMarker(stateDir);
+    tld = readTldFromDir(stateDir);
     if (!await waitForProxy(defaultPort, void 0, void 0, autoTls)) {
       console.error(chalk.red("Proxy failed to start (timed out waiting for it to listen)."));
       const logPath = path3.join(stateDir, "proxy.log");
@@ -918,7 +978,7 @@ portless
       PORT: port.toString(),
       HOST: "127.0.0.1",
       PORTLESS_URL: finalUrl,
-      __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: ".localhost"
+      __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: `.${tld}`
     },
     onCleanup: () => {
       try {
@@ -953,6 +1013,7 @@ function appPortFromEnv() {
 function parseRunArgs(args) {
   let force = false;
   let appPort;
+  let name;
   let i = 0;
   while (i < args.length && args[i].startsWith("-")) {
     if (args[i] === "--") {
@@ -966,6 +1027,7 @@ ${chalk.bold("Usage:")}
   ${chalk.cyan("portless run [options] <command...>")}
 
 ${chalk.bold("Options:")}
+  --name <name>          Override the inferred base name (worktree prefix still applies)
   --force                Override an existing route registered by another process
   --app-port <number>    Use a fixed port for the app (skip auto-assignment)
   --help, -h             Show this help
@@ -975,11 +1037,13 @@ ${chalk.bold("Name inference (in order):")}
   2. Git repo root directory name
   3. Current directory basename
 
+  Use --name to override the inferred name while keeping worktree prefixes.
   In git worktrees, the branch name is prepended as a subdomain prefix
   (e.g. feature-auth.myapp.localhost).
 
 ${chalk.bold("Examples:")}
   portless run next dev               # -> http://<project>.localhost:1355
+  portless run --name myapp next dev  # -> http://myapp.localhost:1355
   portless run vite dev               # -> http://<project>.localhost:1355
   portless run --app-port 3000 pnpm start
 `);
@@ -989,15 +1053,23 @@ ${chalk.bold("Examples:")}
     } else if (args[i] === "--app-port") {
       i++;
       appPort = parseAppPort(args[i]);
+    } else if (args[i] === "--name") {
+      i++;
+      if (!args[i] || args[i].startsWith("-")) {
+        console.error(chalk.red("Error: --name requires a name value."));
+        console.error(chalk.cyan("  portless run --name <name> <command...>"));
+        process.exit(1);
+      }
+      name = args[i];
     } else {
       console.error(chalk.red(`Error: Unknown flag "${args[i]}".`));
-      console.error(chalk.blue("Known flags: --force, --app-port, --help"));
+      console.error(chalk.blue("Known flags: --name, --force, --app-port, --help"));
       process.exit(1);
     }
     i++;
   }
   if (!appPort) appPort = appPortFromEnv();
-  return { force, appPort, commandArgs: args.slice(i) };
+  return { force, appPort, name, commandArgs: args.slice(i) };
 }
 function parseAppArgs(args) {
   let force = false;
@@ -1058,6 +1130,7 @@ ${chalk.bold("Usage:")}
   ${chalk.cyan("portless proxy stop")}              Stop the proxy
   ${chalk.cyan("portless <name> <cmd>")}            Run your app through the proxy
   ${chalk.cyan("portless run <cmd>")}               Infer name from project, run through proxy
+  ${chalk.cyan("portless get <name>")}              Print URL for a service (for cross-service refs)
   ${chalk.cyan("portless alias <name> <port>")}     Register a static route (e.g. for Docker)
   ${chalk.cyan("portless alias --remove <name>")}   Remove a static route
   ${chalk.cyan("portless list")}                    Show active routes
@@ -1073,6 +1146,7 @@ ${chalk.bold("Examples:")}
   portless api.myapp pnpm start       # -> http://api.myapp.localhost:1355
   portless run next dev               # -> http://<project>.localhost:1355
   portless run next dev               # in worktree -> http://<worktree>.<project>.localhost:1355
+  portless get backend                 # -> http://backend.localhost:1355 (for cross-service refs)
   # Wildcard subdomains: tenant.myapp.localhost also routes to myapp
 
 ${chalk.bold("In package.json:")}
@@ -1097,7 +1171,7 @@ ${chalk.bold("HTTP/2 + HTTPS:")}
   system trust store. No browser warnings. No sudo required on macOS.
 
 ${chalk.bold("Options:")}
-  run <cmd>                      Infer project name from package.json / git / cwd
+  run [--name <name>] <cmd>      Infer project name (or override with --name)
                                 Adds worktree prefix in git worktrees
   -p, --port <number>           Port for the proxy to listen on (default: 1355)
                                 Ports < 1024 require sudo
@@ -1106,6 +1180,7 @@ ${chalk.bold("Options:")}
   --key <path>                  Use a custom TLS private key (implies --https)
   --no-tls                      Disable HTTPS (overrides PORTLESS_HTTPS)
   --foreground                  Run proxy in foreground (for debugging)
+  --tld <tld>                   Use a custom TLD instead of .localhost (e.g. test, dev)
   --app-port <number>           Use a fixed port for the app (skip auto-assignment)
   --force                       Override an existing route registered by another process
   --name <name>                 Use <name> as the app name (bypasses subcommand dispatch)
@@ -1114,10 +1189,11 @@ ${chalk.bold("Options:")}
 ${chalk.bold("Environment variables:")}
   PORTLESS_PORT=<number>        Override the default proxy port (e.g. in .bashrc)
   PORTLESS_APP_PORT=<number>    Use a fixed port for the app (same as --app-port)
-  PORTLESS_HTTPS=1|true         Always enable HTTPS (set in .bashrc / .zshrc)
-  PORTLESS_SYNC_HOSTS=1         Auto-sync /etc/hosts (requires sudo proxy start)
+  PORTLESS_HTTPS=1              Always enable HTTPS (set in .bashrc / .zshrc)
+  PORTLESS_TLD=<tld>            Use a custom TLD (e.g. test, dev; default: localhost)
+  PORTLESS_SYNC_HOSTS=1         Auto-sync /etc/hosts (auto-enabled for custom TLDs)
   PORTLESS_STATE_DIR=<path>     Override the state directory
-  PORTLESS=0 | PORTLESS=skip    Run command directly without proxy
+  PORTLESS=0                    Run command directly without proxy
 
 ${chalk.bold("Child process environment:")}
   PORT                          Ephemeral port the child should listen on
@@ -1127,26 +1203,24 @@ ${chalk.bold("Child process environment:")}
 ${chalk.bold("Safari / DNS:")}
   .localhost subdomains auto-resolve in Chrome, Firefox, and Edge.
   Safari relies on the system DNS resolver, which may not handle them.
-  If Safari can't find your .localhost URL, run:
+  Auto-syncs /etc/hosts for custom TLDs (e.g. --tld test). For .localhost,
+  set PORTLESS_SYNC_HOSTS=1 to enable. To manually sync:
     ${chalk.cyan("sudo portless hosts sync")}
-  This adds entries to /etc/hosts. Clean up later with:
+  Clean up later with:
     ${chalk.cyan("sudo portless hosts clean")}
-  To auto-sync whenever routes change, set PORTLESS_SYNC_HOSTS=1 and
-  start the proxy with sudo.
 
 ${chalk.bold("Skip portless:")}
   PORTLESS=0 pnpm dev           # Runs command directly without proxy
-  PORTLESS=skip pnpm dev        # Same as above
 
 ${chalk.bold("Reserved names:")}
-  run, alias, hosts, list, trust, proxy are subcommands and cannot be
-  used as app names directly. Use "portless run" to infer the name, or
-  "portless --name <name>" to force any name including reserved ones.
+  run, get, alias, hosts, list, trust, proxy are subcommands and cannot
+  be used as app names directly. Use "portless run" to infer the name,
+  or "portless --name <name>" to force any name including reserved ones.
 `);
   process.exit(0);
 }
 function printVersion() {
-  console.log("0.5.1");
+  console.log("0.6.0");
   process.exit(0);
 }
 async function handleTrust() {
@@ -1171,6 +1245,60 @@ async function handleList() {
   });
   listRoutes(store, port, tls2);
 }
+async function handleGet(args) {
+  if (args[1] === "--help" || args[1] === "-h") {
+    console.log(`
+${chalk.bold("portless get")} - Print the URL for a service.
+
+${chalk.bold("Usage:")}
+  ${chalk.cyan("portless get <name>")}
+
+Constructs the URL using the same hostname and worktree logic as
+"portless run", then prints it to stdout. Useful for wiring services
+together:
+
+  BACKEND_URL=$(portless get backend)
+
+${chalk.bold("Options:")}
+  --no-worktree          Skip worktree prefix detection
+  --help, -h             Show this help
+
+${chalk.bold("Examples:")}
+  portless get backend                  # -> http://backend.localhost:1355
+  portless get backend                  # in worktree -> http://auth.backend.localhost:1355
+  portless get backend --no-worktree    # -> http://backend.localhost:1355 (skip worktree)
+`);
+    process.exit(0);
+  }
+  let skipWorktree = false;
+  const positional = [];
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--no-worktree") {
+      skipWorktree = true;
+    } else if (args[i].startsWith("-")) {
+      console.error(chalk.red(`Error: Unknown flag "${args[i]}".`));
+      console.error(chalk.blue("Known flags: --no-worktree, --help"));
+      process.exit(1);
+    } else {
+      positional.push(args[i]);
+    }
+  }
+  if (positional.length === 0) {
+    console.error(chalk.red("Error: Missing service name."));
+    console.error(chalk.blue("Usage:"));
+    console.error(chalk.cyan("  portless get <name>"));
+    console.error(chalk.blue("Example:"));
+    console.error(chalk.cyan("  portless get backend"));
+    process.exit(1);
+  }
+  const name = positional[0];
+  const worktree = skipWorktree ? null : detectWorktreePrefix();
+  const effectiveName = worktree ? `${worktree.prefix}.${name}` : name;
+  const { port, tls: tls2, tld } = await discoverState();
+  const hostname = parseHostname(effectiveName, tld);
+  const url = formatUrl(hostname, port, tls2);
+  process.stdout.write(url + "\n");
+}
 async function handleAlias(args) {
   if (args[1] === "--help" || args[1] === "-h") {
     console.log(`
@@ -1188,7 +1316,7 @@ ${chalk.bold("Examples:")}
 `);
     process.exit(0);
   }
-  const { dir } = await discoverState();
+  const { dir, tld } = await discoverState();
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(chalk.yellow(msg))
   });
@@ -1199,7 +1327,7 @@ ${chalk.bold("Examples:")}
       console.error(chalk.cyan("  portless alias --remove <name>"));
       process.exit(1);
     }
-    const hostname2 = parseHostname(aliasName2);
+    const hostname2 = parseHostname(aliasName2, tld);
     const routes = store.loadRoutes();
     const existing = routes.find((r) => r.hostname === hostname2 && r.pid === 0);
     if (!existing) {
@@ -1221,7 +1349,7 @@ ${chalk.bold("Examples:")}
     console.error(chalk.cyan("  portless alias my-postgres 5432"));
     process.exit(1);
   }
-  const hostname = parseHostname(aliasName);
+  const hostname = parseHostname(aliasName, tld);
   const port = parseInt(aliasPort, 10);
   if (isNaN(port) || port < 1 || port > 65535) {
     console.error(chalk.red(`Error: Invalid port "${aliasPort}". Must be 1-65535.`));
@@ -1229,7 +1357,7 @@ ${chalk.bold("Examples:")}
   }
   const force = args.includes("--force");
   store.addRoute(hostname, port, 0, force);
-  console.log(chalk.green(`Alias registered: ${hostname} -> localhost:${port}`));
+  console.log(chalk.green(`Alias registered: ${hostname} -> 127.0.0.1:${port}`));
 }
 async function handleHosts(args) {
   if (args[1] === "--help" || args[1] === "-h") {
@@ -1244,8 +1372,8 @@ ${chalk.bold("Usage:")}
   ${chalk.cyan("sudo portless hosts clean")}   Remove portless entries from /etc/hosts
 
 ${chalk.bold("Auto-sync:")}
-  Set PORTLESS_SYNC_HOSTS=1 and start the proxy with sudo to auto-sync
-  /etc/hosts whenever routes change.
+  Auto-enabled for custom TLDs (e.g. --tld test). For .localhost, set
+  PORTLESS_SYNC_HOSTS=1 to enable. Disable with PORTLESS_SYNC_HOSTS=0.
 `);
     process.exit(0);
   }
@@ -1315,6 +1443,7 @@ ${chalk.bold("Usage:")}
   ${chalk.cyan("portless proxy start --https")}        Start with HTTP/2 + TLS
   ${chalk.cyan("portless proxy start --foreground")}   Start in foreground (for debugging)
   ${chalk.cyan("portless proxy start -p 80")}          Start on port 80 (requires sudo)
+  ${chalk.cyan("portless proxy start --tld test")}     Use .test instead of .localhost
   ${chalk.cyan("portless proxy stop")}                 Stop the proxy
 `);
     process.exit(isProxyHelp || !args[1] ? 0 : 1);
@@ -1363,6 +1492,39 @@ ${chalk.bold("Usage:")}
     console.error(chalk.red("Error: --cert and --key must be used together."));
     process.exit(1);
   }
+  let tld;
+  try {
+    tld = getDefaultTld();
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+  const tldIdx = args.indexOf("--tld");
+  if (tldIdx !== -1) {
+    const tldValue = args[tldIdx + 1];
+    if (!tldValue || tldValue.startsWith("-")) {
+      console.error(chalk.red("Error: --tld requires a TLD value (e.g. test, localhost)."));
+      process.exit(1);
+    }
+    tld = tldValue.trim().toLowerCase();
+    const tldErr = validateTld(tld);
+    if (tldErr) {
+      console.error(chalk.red(`Error: ${tldErr}`));
+      process.exit(1);
+    }
+  }
+  const riskyReason = RISKY_TLDS.get(tld);
+  if (riskyReason) {
+    console.warn(chalk.yellow(`Warning: .${tld} -- ${riskyReason}`));
+  }
+  const syncDisabled = process.env.PORTLESS_SYNC_HOSTS === "0" || process.env.PORTLESS_SYNC_HOSTS === "false";
+  if (tld !== DEFAULT_TLD && syncDisabled) {
+    console.warn(
+      chalk.yellow(`Warning: .${tld} domains require /etc/hosts entries to resolve to 127.0.0.1.`)
+    );
+    console.warn(chalk.yellow("Hosts sync is disabled. To add entries manually, run:"));
+    console.warn(chalk.cyan("  sudo portless hosts sync"));
+  }
   const useHttps = wantHttps || !!(customCertPath && customKeyPath);
   const stateDir = resolveStateDir(proxyPort);
   const store = new RouteStore(stateDir, {
@@ -1374,8 +1536,13 @@ ${chalk.bold("Usage:")}
     }
     const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
     const sudoPrefix = needsSudo ? "sudo " : "";
+    const portFlag = proxyPort !== getDefaultPort() ? ` -p ${proxyPort}` : "";
     console.log(chalk.yellow(`Proxy is already running on port ${proxyPort}.`));
-    console.log(chalk.blue(`To restart: portless proxy stop && ${sudoPrefix}portless proxy start`));
+    console.log(
+      chalk.blue(
+        `To restart: ${sudoPrefix}portless proxy stop${portFlag} && ${sudoPrefix}portless proxy start${portFlag}`
+      )
+    );
     return;
   }
   if (proxyPort < PRIVILEGED_PORT_THRESHOLD && (process.getuid?.() ?? -1) !== 0) {
@@ -1440,13 +1607,13 @@ ${chalk.bold("Usage:")}
       tlsOptions = {
         cert,
         key,
-        SNICallback: createSNICallback(stateDir, cert, key)
+        SNICallback: createSNICallback(stateDir, cert, key, tld)
       };
     }
   }
   if (isForeground) {
     console.log(chalk.blue.bold("\nportless proxy\n"));
-    startProxyServer(store, proxyPort, tlsOptions);
+    startProxyServer(store, proxyPort, tld, tlsOptions);
     return;
   }
   store.ensureDir();
@@ -1469,6 +1636,9 @@ ${chalk.bold("Usage:")}
         daemonArgs.push("--https");
       }
     }
+    if (tld !== DEFAULT_TLD) {
+      daemonArgs.push("--tld", tld);
+    }
     const child = spawn(process.execPath, daemonArgs, {
       detached: true,
       stdio: ["ignore", logFd, logFd],
@@ -1501,10 +1671,24 @@ async function handleRunMode(args) {
     console.error(chalk.cyan("  portless run next dev"));
     process.exit(1);
   }
-  const inferred = inferProjectName();
+  let baseName;
+  let nameSource;
+  if (parsed.name) {
+    const sanitized = sanitizeForHostname(parsed.name);
+    if (!sanitized) {
+      console.error(chalk.red(`Error: --name value "${parsed.name}" produces an empty hostname.`));
+      process.exit(1);
+    }
+    baseName = sanitized;
+    nameSource = "--name flag";
+  } else {
+    const inferred = inferProjectName();
+    baseName = inferred.name;
+    nameSource = inferred.source;
+  }
   const worktree = detectWorktreePrefix();
-  const effectiveName = worktree ? `${worktree.prefix}.${inferred.name}` : inferred.name;
-  const { dir, port, tls: tls2 } = await discoverState();
+  const effectiveName = worktree ? `${worktree.prefix}.${baseName}` : baseName;
+  const { dir, port, tls: tls2, tld } = await discoverState();
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(chalk.yellow(msg))
   });
@@ -1515,8 +1699,9 @@ async function handleRunMode(args) {
     effectiveName,
     parsed.commandArgs,
     tls2,
+    tld,
     parsed.force,
-    { nameSource: inferred.source, prefix: worktree?.prefix, prefixSource: worktree?.source },
+    { nameSource, prefix: worktree?.prefix, prefixSource: worktree?.source },
     parsed.appPort
   );
 }
@@ -1530,7 +1715,7 @@ async function handleNamedMode(args) {
     console.error(chalk.cyan("  portless myapp next dev"));
     process.exit(1);
   }
-  const { dir, port, tls: tls2 } = await discoverState();
+  const { dir, port, tls: tls2, tld } = await discoverState();
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(chalk.yellow(msg))
   });
@@ -1541,6 +1726,7 @@ async function handleNamedMode(args) {
     parsed.name,
     parsed.commandArgs,
     tls2,
+    tld,
     parsed.force,
     void 0,
     parsed.appPort
@@ -1571,7 +1757,7 @@ async function main() {
       console.error(chalk.cyan("  portless --name <name> <command...>"));
       process.exit(1);
     }
-    const skipPortless2 = process.env.PORTLESS === "0" || process.env.PORTLESS === "skip";
+    const skipPortless2 = process.env.PORTLESS === "0" || process.env.PORTLESS === "false" || process.env.PORTLESS === "skip";
     if (skipPortless2) {
       const { commandArgs } = parseAppArgs(args);
       if (commandArgs.length === 0) {
@@ -1588,7 +1774,7 @@ async function main() {
   if (isRunCommand) {
     args.shift();
   }
-  const skipPortless = process.env.PORTLESS === "0" || process.env.PORTLESS === "skip";
+  const skipPortless = process.env.PORTLESS === "0" || process.env.PORTLESS === "false" || process.env.PORTLESS === "skip";
   if (skipPortless && (isRunCommand || args.length >= 2 && args[0] !== "proxy")) {
     const { commandArgs } = isRunCommand ? parseRunArgs(args) : parseAppArgs(args);
     if (commandArgs.length === 0) {
@@ -1615,6 +1801,10 @@ async function main() {
       await handleList();
       return;
     }
+    if (args[0] === "get") {
+      await handleGet(args);
+      return;
+    }
     if (args[0] === "alias") {
       await handleAlias(args);
       return;

package/dist/index.d.ts

@@ -12,6 +12,8 @@ interface ProxyServerOptions {
     getRoutes: () => RouteInfo[];
     /** The port the proxy is listening on (used to build correct URLs). */
     proxyPort: number;
+    /** TLD suffix used for hostnames (default: "localhost"). */
+    tld?: string;
     /** Optional error logger; defaults to console.error. */
     onError?: (message: string) => void;
     /** When provided, enables HTTP/2 over TLS (HTTPS). */
@@ -109,15 +111,16 @@ declare function isErrnoException(err: unknown): err is NodeJS.ErrnoException;
  */
 declare function escapeHtml(str: string): string;
 /**
- * Format a .localhost URL. Omits the port when it matches the protocol default
- * (80 for HTTP, 443 for HTTPS).
+ * Format a URL for the given hostname. Omits the port when it matches the
+ * protocol default (80 for HTTP, 443 for HTTPS).
  */
 declare function formatUrl(hostname: string, proxyPort: number, tls?: boolean): string;
 /**
- * Parse and normalize a hostname input for use as a .localhost subdomain.
- * Strips protocol prefixes, validates characters, and appends .localhost if needed.
+ * Parse and normalize a hostname input for use as a subdomain of the
+ * configured TLD. Strips protocol prefixes, validates characters, and
+ * appends the TLD suffix if needed.
  */
-declare function parseHostname(input: string): string;
+declare function parseHostname(input: string, tld?: string): string;
 
 /**
  * Extract the portless-managed block from /etc/hosts content.
@@ -150,9 +153,9 @@ declare function cleanHostsFile(): boolean;
  */
 declare function getManagedHostnames(): string[];
 /**
- * Check whether a .localhost subdomain resolves to 127.0.0.1 via the
- * system DNS resolver. Returns true if resolution works, false otherwise.
+ * Check whether a hostname resolves to 127.0.0.1 via the system DNS resolver.
+ * Returns true if resolution works, false otherwise.
  */
-declare function checkLocalhostResolution(hostname: string): Promise<boolean>;
+declare function checkHostResolution(hostname: string): Promise<boolean>;
 
-export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, SYSTEM_DIR_MODE, SYSTEM_FILE_MODE, buildBlock, checkLocalhostResolution, cleanHostsFile, createProxyServer, escapeHtml, extractManagedBlock, fixOwnership, formatUrl, getManagedHostnames, isErrnoException, parseHostname, removeBlock, syncHostsFile };
+export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, SYSTEM_DIR_MODE, SYSTEM_FILE_MODE, buildBlock, checkHostResolution, cleanHostsFile, createProxyServer, escapeHtml, extractManagedBlock, fixOwnership, formatUrl, getManagedHostnames, isErrnoException, parseHostname, removeBlock, syncHostsFile };

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   SYSTEM_DIR_MODE,
   SYSTEM_FILE_MODE,
   buildBlock,
-  checkLocalhostResolution,
+  checkHostResolution,
   cleanHostsFile,
   createProxyServer,
   escapeHtml,
@@ -19,7 +19,7 @@ import {
   parseHostname,
   removeBlock,
   syncHostsFile
-} from "./chunk-P3DHZHEZ.js";
+} from "./chunk-AB3HUERH.js";
 export {
   DIR_MODE,
   FILE_MODE,
@@ -29,7 +29,7 @@ export {
   SYSTEM_DIR_MODE,
   SYSTEM_FILE_MODE,
   buildBlock,
-  checkLocalhostResolution,
+  checkHostResolution,
   cleanHostsFile,
   createProxyServer,
   escapeHtml,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portless",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Replace port numbers with stable, named .localhost URLs. For humans and agents.",
   "type": "module",
   "main": "./dist/index.js",