portless 0.8.0 → 0.9.1

package/dist/cli.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 import {
   DEFAULT_TLD,
+  FALLBACK_PROXY_PORT,
   FILE_MODE,
   PRIVILEGED_PORT_THRESHOLD,
   RISKY_TLDS,
   RouteConflictError,
   RouteStore,
+  WAIT_FOR_PROXY_INTERVAL_MS,
+  WAIT_FOR_PROXY_MAX_ATTEMPTS,
   cleanHostsFile,
+  createHttpRedirectServer,
   createProxyServer,
   discoverState,
   findFreePort,
@@ -15,16 +19,15 @@ import {
   formatUrl,
   getDefaultPort,
   getDefaultTld,
+  getProtocolPort,
   injectFrameworkFlags,
   isErrnoException,
-  isHttpsEnvEnabled,
+  isHttpsEnvDisabled,
   isProxyRunning,
   isWildcardEnvEnabled,
   isWindows,
   parseHostname,
   prompt,
-  readTldFromDir,
-  readTlsMarker,
   resolveStateDir,
   spawnCommand,
   syncHostsFile,
@@ -32,7 +35,7 @@ import {
   waitForProxy,
   writeTldFile,
   writeTlsMarker
-} from "./chunk-KKXL2CMI.js";
+} from "./chunk-5BR7NCNI.js";
 
 // src/colors.ts
 function supportsColor() {
@@ -488,7 +491,10 @@ function createSNICallback(stateDir, defaultCert, defaultKey, tld = "localhost")
 function trustCA(stateDir) {
   const caCertPath = path.join(stateDir, CA_CERT_FILE);
   if (!fileExists(caCertPath)) {
-    return { trusted: false, error: "CA certificate not found. Run with --https first." };
+    return {
+      trusted: false,
+      error: "CA certificate not found. Run portless trust to generate it."
+    };
   }
   try {
     if (process.platform === "darwin") {
@@ -538,7 +544,7 @@ function trustCA(stateDir) {
     if (message.includes("authorization") || message.includes("permission") || message.includes("EACCES")) {
       return {
         trusted: false,
-        error: "Permission denied. Try: sudo portless trust"
+        error: "Permission denied. Try: portless trust"
       };
     }
     return { trusted: false, error: message };
@@ -721,11 +727,47 @@ function readBranchFromHead(gitdir) {
 
 // src/cli.ts
 var HOSTS_DISPLAY = isWindows ? "hosts file" : "/etc/hosts";
-var SUDO_PREFIX = isWindows ? "" : "sudo ";
 var DEBOUNCE_MS = 100;
 var POLL_INTERVAL_MS = 3e3;
 var EXIT_TIMEOUT_MS = 2e3;
 var SUDO_SPAWN_TIMEOUT_MS = 3e4;
+function getEntryScript() {
+  const script = process.argv[1];
+  if (!script) {
+    throw new Error("Cannot determine portless entry script (process.argv[1] is undefined)");
+  }
+  return script;
+}
+function isLocallyInstalled() {
+  let dir = process.cwd();
+  for (; ; ) {
+    if (fs3.existsSync(path3.join(dir, "node_modules", "portless", "package.json"))) {
+      return true;
+    }
+    const parent = path3.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+function collectPortlessEnvArgs() {
+  const envArgs = [];
+  for (const key of Object.keys(process.env)) {
+    if (key.startsWith("PORTLESS_") && process.env[key]) {
+      envArgs.push(`${key}=${process.env[key]}`);
+    }
+  }
+  return envArgs;
+}
+function sudoStop(port) {
+  const stopArgs = [process.execPath, getEntryScript(), "proxy", "stop", "-p", String(port)];
+  console.log(colors_default.yellow("Proxy is running as root. Elevating with sudo to stop it..."));
+  const result = spawnSync("sudo", ["env", ...collectPortlessEnvArgs(), ...stopArgs], {
+    stdio: "inherit",
+    timeout: SUDO_SPAWN_TIMEOUT_MS
+  });
+  return result.status === 0;
+}
 function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
   store.ensureDir();
   const isTls = !!tlsOptions;
@@ -786,15 +828,22 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
       );
     } else if (err.code === "EACCES") {
       console.error(colors_default.red(`Permission denied for port ${proxyPort}.`));
-      console.error(colors_default.blue("Either run with sudo:"));
-      console.error(colors_default.cyan("  sudo portless proxy start -p 80"));
-      console.error(colors_default.blue("Or use a non-privileged port (no sudo needed):"));
-      console.error(colors_default.cyan("  portless proxy start"));
+      console.error(colors_default.blue("Use an unprivileged port (no sudo needed):"));
+      console.error(colors_default.cyan("  portless proxy start -p 1355"));
     } else {
       console.error(colors_default.red(`Proxy error: ${err.message}`));
     }
+    if (redirectServer) redirectServer.close();
     process.exit(1);
   });
+  let redirectServer = null;
+  if (isTls && proxyPort !== 80) {
+    redirectServer = createHttpRedirectServer(proxyPort);
+    redirectServer.on("error", () => {
+      redirectServer = null;
+    });
+    redirectServer.listen(80);
+  }
   server.listen(proxyPort, () => {
     fs3.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
     fs3.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
@@ -807,6 +856,9 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
     console.log(
       colors_default.green(`${proto} proxy listening on port ${proxyPort}${tldLabel}${modeLabel}`)
     );
+    if (redirectServer) {
+      console.log(colors_default.green("HTTP-to-HTTPS redirect listening on port 80"));
+    }
   });
   let exiting = false;
   const cleanup = () => {
@@ -817,6 +869,9 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
     if (watcher) {
       watcher.close();
     }
+    if (redirectServer) {
+      redirectServer.close();
+    }
     try {
       fs3.unlinkSync(store.pidPath);
     } catch {
@@ -836,10 +891,21 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, strict) {
   console.log(colors_default.cyan("\nProxy is running. Press Ctrl+C to stop.\n"));
   console.log(colors_default.gray(`Routes file: ${store.getRoutesPath()}`));
 }
+function sudoStopOrHint(port) {
+  if (!isWindows) {
+    if (!sudoStop(port)) {
+      console.error(colors_default.red("Failed to stop proxy with sudo."));
+      console.error(colors_default.blue("Try manually:"));
+      console.error(colors_default.cyan(`  portless proxy stop -p ${port}`));
+    }
+  } else {
+    console.error(colors_default.red("Permission denied. The proxy was started with elevated privileges."));
+    console.error(colors_default.blue("Stop it with:"));
+    console.error(colors_default.cyan("  Run portless proxy stop as Administrator"));
+  }
+}
 async function stopProxy(store, proxyPort, _tls) {
   const pidPath = store.pidPath;
-  const needsSudo = !isWindows && proxyPort < PRIVILEGED_PORT_THRESHOLD;
-  const sudoHint = needsSudo ? "sudo " : "";
   if (!fs3.existsSync(pidPath)) {
     if (await isProxyRunning(proxyPort)) {
       console.log(colors_default.yellow(`PID file is missing but port ${proxyPort} is still in use.`));
@@ -854,15 +920,7 @@ async function stopProxy(store, proxyPort, _tls) {
           console.log(colors_default.green(`Killed process ${pid}. Proxy stopped.`));
         } catch (err) {
           if (isErrnoException(err) && err.code === "EPERM") {
-            console.error(
-              colors_default.red("Permission denied. The proxy was started with elevated privileges.")
-            );
-            console.error(colors_default.blue("Stop it with:"));
-            console.error(
-              colors_default.cyan(
-                isWindows ? "  Run portless proxy stop as Administrator" : "  sudo portless proxy stop"
-              )
-            );
+            sudoStopOrHint(proxyPort);
           } else {
             const message = err instanceof Error ? err.message : String(err);
             console.error(colors_default.red(`Failed to stop proxy: ${message}`));
@@ -875,9 +933,7 @@ async function stopProxy(store, proxyPort, _tls) {
           }
         }
       } else if (!isWindows && process.getuid?.() !== 0) {
-        console.error(colors_default.red("Cannot identify the process. It may be running as root."));
-        console.error(colors_default.blue("Try stopping with sudo:"));
-        console.error(colors_default.cyan("  sudo portless proxy stop"));
+        sudoStopOrHint(proxyPort);
       } else {
         console.error(colors_default.red(`Could not identify the process on port ${proxyPort}.`));
         console.error(colors_default.blue("Try manually:"));
@@ -901,7 +957,11 @@ async function stopProxy(store, proxyPort, _tls) {
     }
     try {
       process.kill(pid, 0);
-    } catch {
+    } catch (err) {
+      if (isErrnoException(err) && err.code === "EPERM") {
+        sudoStopOrHint(proxyPort);
+        return;
+      }
       console.log(colors_default.yellow("Proxy process is no longer running. Cleaning up stale files."));
       fs3.unlinkSync(pidPath);
       try {
@@ -929,11 +989,7 @@ async function stopProxy(store, proxyPort, _tls) {
     console.log(colors_default.green("Proxy stopped."));
   } catch (err) {
     if (isErrnoException(err) && err.code === "EPERM") {
-      console.error(
-        colors_default.red("Permission denied. The proxy was started with elevated privileges.")
-      );
-      console.error(colors_default.blue("Stop it with:"));
-      console.error(colors_default.cyan(`  ${sudoHint}portless proxy stop`));
+      sudoStopOrHint(proxyPort);
     } else {
       const message = err instanceof Error ? err.message : String(err);
       console.error(colors_default.red(`Failed to stop proxy: ${message}`));
@@ -963,8 +1019,8 @@ function listRoutes(store, proxyPort, tls2) {
   }
   console.log();
 }
-async function runApp(store, proxyPort, stateDir, name, commandArgs, tls2, tld, force, autoInfo, desiredPort) {
-  const hostname = parseHostname(name, tld);
+async function runApp(initialStore, proxyPort, stateDir, name, commandArgs, tls2, tld, force, autoInfo, desiredPort) {
+  let store = initialStore;
   let envTld;
   try {
     envTld = getDefaultTld();
@@ -982,7 +1038,7 @@ async function runApp(store, proxyPort, stateDir, name, commandArgs, tls2, tld,
   console.log(colors_default.blue.bold(`
 portless
 `));
-  console.log(colors_default.gray(`-- ${hostname} (auto-resolves to 127.0.0.1)`));
+  console.log(colors_default.gray(`-- ${parseHostname(name, tld)} (auto-resolves to 127.0.0.1)`));
   if (autoInfo) {
     const baseName = autoInfo.prefix ? name.slice(autoInfo.prefix.length + 1) : name;
     console.log(colors_default.gray(`-- Name "${baseName}" (from ${autoInfo.nameSource})`));
@@ -991,18 +1047,22 @@ portless
     }
   }
   if (!await isProxyRunning(proxyPort, tls2)) {
-    const defaultPort = getDefaultPort();
+    const wantTls = !isHttpsEnvDisabled();
+    const defaultPort = getDefaultPort(wantTls);
     const needsSudo = !isWindows && defaultPort < PRIVILEGED_PORT_THRESHOLD;
-    const wantHttps = isHttpsEnvEnabled();
-    if (needsSudo) {
-      if (!process.stdin.isTTY) {
-        console.error(colors_default.red("Proxy is not running."));
-        console.error(colors_default.blue("Start the proxy first (requires sudo for this port):"));
-        console.error(colors_default.cyan("  sudo portless proxy start -p 80"));
-        console.error(colors_default.blue("Or use the default port (no sudo needed):"));
-        console.error(colors_default.cyan("  portless proxy start"));
-        process.exit(1);
-      }
+    if (needsSudo && !process.stdin.isTTY) {
+      console.error(colors_default.red("Proxy is not running and no TTY is available for sudo."));
+      console.error(colors_default.blue("Option 1: start the proxy in a terminal (will prompt for sudo):"));
+      console.error(colors_default.cyan("  portless proxy start"));
+      console.error(
+        colors_default.blue(
+          `Option 2: use an unprivileged port (no sudo needed, URLs will include :${FALLBACK_PROXY_PORT}):`
+        )
+      );
+      console.error(colors_default.cyan(`  portless proxy start -p ${FALLBACK_PROXY_PORT}`));
+      process.exit(1);
+    }
+    if (needsSudo && process.stdin.isTTY) {
       const answer = await prompt(colors_default.yellow("Proxy not running. Start it? [Y/n/skip] "));
       if (answer === "n" || answer === "no") {
         console.log(colors_default.gray("Cancelled."));
@@ -1013,57 +1073,50 @@ portless
         spawnCommand(commandArgs);
         return;
       }
-      console.log(colors_default.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
-      });
-      if (result.status !== 0) {
-        if (!await isProxyRunning(proxyPort)) {
-          console.error(colors_default.red("Failed to start proxy."));
-          console.error(colors_default.blue("Try starting it manually:"));
-          console.error(colors_default.cyan("  sudo portless proxy start"));
-          process.exit(1);
-        }
-      }
-    } else {
-      console.log(colors_default.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
-      });
-      if (result.status !== 0) {
-        if (!await isProxyRunning(proxyPort)) {
-          console.error(colors_default.red("Failed to start proxy."));
-          console.error(colors_default.blue("Try starting it manually:"));
-          console.error(colors_default.cyan("  portless proxy start"));
-          process.exit(1);
+    }
+    console.log(colors_default.yellow("Starting proxy..."));
+    const startArgs = [getEntryScript(), "proxy", "start"];
+    if (!wantTls) startArgs.push("--no-tls");
+    if (tld !== DEFAULT_TLD) startArgs.push("--tld", tld);
+    const result = spawnSync(process.execPath, startArgs, {
+      stdio: "inherit",
+      timeout: SUDO_SPAWN_TIMEOUT_MS
+    });
+    let discovered = null;
+    if (result.status === 0) {
+      for (let i = 0; i < WAIT_FOR_PROXY_MAX_ATTEMPTS; i++) {
+        await new Promise((r) => setTimeout(r, WAIT_FOR_PROXY_INTERVAL_MS));
+        const state = await discoverState();
+        if (await isProxyRunning(state.port)) {
+          discovered = state;
+          break;
         }
       }
     }
-    const autoTls = readTlsMarker(stateDir);
-    tld = readTldFromDir(stateDir);
-    if (!await waitForProxy(defaultPort, void 0, void 0, autoTls)) {
-      console.error(colors_default.red("Proxy failed to start (timed out waiting for it to listen)."));
-      const logPath = path3.join(stateDir, "proxy.log");
-      console.error(colors_default.blue("Try starting the proxy manually to see the error:"));
-      console.error(colors_default.cyan(`  ${needsSudo ? "sudo " : ""}portless proxy start`));
+    if (!discovered) {
+      console.error(colors_default.red("Failed to start proxy."));
+      const fallbackDir = resolveStateDir(getDefaultPort(wantTls));
+      const logPath = path3.join(fallbackDir, "proxy.log");
+      console.error(colors_default.blue("Try starting it manually:"));
+      console.error(colors_default.cyan("  portless proxy start"));
       if (fs3.existsSync(logPath)) {
         console.error(colors_default.gray(`Logs: ${logPath}`));
       }
       process.exit(1);
+      return;
     }
-    tls2 = autoTls;
+    proxyPort = discovered.port;
+    stateDir = discovered.dir;
+    tld = discovered.tld;
+    tls2 = discovered.tls;
+    store = new RouteStore(stateDir, {
+      onWarning: (msg) => console.warn(colors_default.yellow(msg))
+    });
     console.log(colors_default.green("Proxy started in background"));
   } else {
     console.log(colors_default.gray("-- Proxy is running"));
   }
+  const hostname = parseHostname(name, tld);
   const port = desiredPort ?? await findFreePort();
   if (desiredPort) {
     console.log(colors_default.green(`-- Using port ${port} (fixed)`));
@@ -1160,9 +1213,9 @@ ${colors_default.bold("Name inference (in order):")}
   (e.g. feature-auth.myapp.localhost).
 
 ${colors_default.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 next dev               # -> https://<project>.localhost
+  portless run --name myapp next dev  # -> https://myapp.localhost
+  portless run vite dev               # -> https://<project>.localhost
   portless run --app-port 3000 pnpm start
 `);
       process.exit(0);
@@ -1238,13 +1291,13 @@ Eliminates port conflicts, memorizing port numbers, and cookie/storage
 clashes by giving each dev server a stable .localhost URL.
 
 ${colors_default.bold("Install:")}
-  ${colors_default.cyan("npm install -g portless")}
-  Do NOT add portless as a project dependency.
+  ${colors_default.cyan("npm install -g portless")}          Global (recommended)
+  ${colors_default.cyan("npm install -D portless")}          Project dev dependency
 
 ${colors_default.bold("Usage:")}
-  ${colors_default.cyan("portless proxy start")}             Start the proxy (background daemon)
-  ${colors_default.cyan("portless proxy start --https")}     Start with HTTP/2 + TLS (auto-generates certs)
-  ${colors_default.cyan("portless proxy start -p 80")}       Start on port 80 (requires sudo)
+  ${colors_default.cyan("portless proxy start")}             Start the proxy (HTTPS on port 443, daemon)
+  ${colors_default.cyan("portless proxy start --no-tls")}    Start without HTTPS (port 80)
+  ${colors_default.cyan("portless proxy start -p 1355")}     Start on a custom port (no sudo)
   ${colors_default.cyan("portless proxy stop")}              Stop the proxy
   ${colors_default.cyan("portless <name> <cmd>")}            Run your app through the proxy
   ${colors_default.cyan("portless run <cmd>")}               Infer name from project, run through proxy
@@ -1257,14 +1310,14 @@ ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless hosts clean")}             Remove portless entries from ${HOSTS_DISPLAY}
 
 ${colors_default.bold("Examples:")}
-  portless proxy start                # Start proxy on port 1355
-  portless proxy start --https        # Start with HTTPS/2 (faster page loads)
-  portless myapp next dev             # -> http://myapp.localhost:1355
-  portless myapp vite dev             # -> http://myapp.localhost:1355
-  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)
+  portless proxy start                # Start HTTPS proxy on port 443
+  portless proxy start --no-tls       # Start HTTP proxy on port 80
+  portless myapp next dev             # -> https://myapp.localhost
+  portless myapp vite dev             # -> https://myapp.localhost
+  portless api.myapp pnpm start       # -> https://api.myapp.localhost
+  portless run next dev               # -> https://<project>.localhost
+  portless run next dev               # in worktree -> https://<worktree>.<project>.localhost
+  portless get backend                 # -> https://backend.localhost (for cross-service refs)
   # Wildcard subdomains: tenant.myapp.localhost also routes to myapp
 
 ${colors_default.bold("In package.json:")}
@@ -1275,28 +1328,28 @@ ${colors_default.bold("In package.json:")}
   }
 
 ${colors_default.bold("How it works:")}
-  1. Start the proxy once (listens on port 1355 by default, no sudo needed)
+  1. Start the proxy once (HTTPS on port 443 by default, auto-elevates with sudo)
   2. Run your apps - they auto-start the proxy and register automatically
      (apps get a random port in the 4000-4999 range via PORT)
-  3. Access via http://<name>.localhost:1355
+  3. Access via https://<name>.localhost
   4. .localhost domains auto-resolve to 127.0.0.1
   5. Frameworks that ignore PORT (Vite, Astro, React Router, Angular,
      Expo, React Native) get --port and --host flags injected automatically
 
-${colors_default.bold("HTTP/2 + HTTPS:")}
-  Use --https for HTTP/2 multiplexing (faster dev server page loads).
+${colors_default.bold("HTTP/2 + HTTPS (default):")}
+  HTTPS with HTTP/2 multiplexing is enabled by default (faster page loads).
   On first use, portless generates a local CA and adds it to your
-  system trust store. No browser warnings. No sudo required on macOS.
+  system trust store. No browser warnings. Disable with --no-tls.
 
 ${colors_default.bold("Options:")}
   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
-  --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)
+  -p, --port <number>           Port for the proxy (default: 443, or 80 with --no-tls)
+                                Standard ports auto-elevate with sudo on macOS/Linux
+  --no-tls                      Disable HTTPS (use plain HTTP on port 80)
+  --https                       Enable HTTPS (default, accepted for compatibility)
+  --cert <path>                 Use a custom TLS certificate
+  --key <path>                  Use a custom TLS private key
   --foreground                  Run proxy in foreground (for debugging)
   --tld <tld>                   Use a custom TLD instead of .localhost (e.g. test, dev)
   --wildcard                    Allow unregistered subdomains to fall back to parent route
@@ -1308,7 +1361,7 @@ ${colors_default.bold("Options:")}
 ${colors_default.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              Always enable HTTPS (set in .bashrc / .zshrc)
+  PORTLESS_HTTPS                HTTPS on by default; set to 0 to disable (same as --no-tls)
   PORTLESS_TLD=<tld>            Use a custom TLD (e.g. test, dev; default: localhost)
   PORTLESS_WILDCARD=1           Allow unregistered subdomains to fall back to parent route
   PORTLESS_SYNC_HOSTS=1         Auto-sync ${HOSTS_DISPLAY} (auto-enabled for custom TLDs)
@@ -1318,16 +1371,16 @@ ${colors_default.bold("Environment variables:")}
 ${colors_default.bold("Child process environment:")}
   PORT                          Ephemeral port the child should listen on
   HOST                          Always 127.0.0.1
-  PORTLESS_URL                  Public URL of the app (e.g. http://myapp.localhost:1355)
+  PORTLESS_URL                  Public URL of the app (e.g. https://myapp.localhost)
 
 ${colors_default.bold("Safari / DNS:")}
   .localhost subdomains auto-resolve in Chrome, Firefox, and Edge.
   Safari relies on the system DNS resolver, which may not handle them.
   Auto-syncs ${HOSTS_DISPLAY} for custom TLDs (e.g. --tld test). For .localhost,
   set PORTLESS_SYNC_HOSTS=1 to enable. To manually sync:
-    ${colors_default.cyan(`${SUDO_PREFIX}portless hosts sync`)}
+    ${colors_default.cyan("portless hosts sync")}
   Clean up later with:
-    ${colors_default.cyan(`${SUDO_PREFIX}portless hosts clean`)}
+    ${colors_default.cyan("portless hosts clean")}
 
 ${colors_default.bold("Skip portless:")}
   PORTLESS=0 pnpm dev           # Runs command directly without proxy
@@ -1340,23 +1393,36 @@ ${colors_default.bold("Reserved names:")}
   process.exit(0);
 }
 function printVersion() {
-  console.log("0.8.0");
+  console.log("0.9.1");
   process.exit(0);
 }
 async function handleTrust() {
   const { dir } = await discoverState();
+  if (!fs3.existsSync(dir)) {
+    fs3.mkdirSync(dir, { recursive: true });
+  }
+  const { caGenerated } = ensureCerts(dir);
+  if (caGenerated) {
+    console.log(colors_default.gray("Generated local CA certificate."));
+  }
   const result = trustCA(dir);
   if (result.trusted) {
     console.log(colors_default.green("Local CA added to system trust store."));
     console.log(colors_default.gray("Browsers will now trust portless HTTPS certificates."));
-  } else {
-    console.error(colors_default.red(`Failed to trust CA: ${result.error}`));
-    if (result.error?.includes("sudo")) {
-      console.error(colors_default.blue("Run with sudo:"));
-      console.error(colors_default.cyan("  sudo portless trust"));
-    }
-    process.exit(1);
+    return;
+  }
+  const isPermissionError = result.error?.includes("Permission denied") || result.error?.includes("EACCES");
+  if (isPermissionError && !isWindows && process.getuid?.() !== 0) {
+    console.log(colors_default.yellow("Trusting the CA requires elevated privileges. Requesting sudo..."));
+    const sudoResult = spawnSync("sudo", [process.execPath, getEntryScript(), "trust"], {
+      stdio: "inherit",
+      timeout: SUDO_SPAWN_TIMEOUT_MS
+    });
+    if (sudoResult.status === 0) return;
+    console.error(colors_default.red("sudo elevation also failed."));
   }
+  console.error(colors_default.red(`Failed to trust CA: ${result.error}`));
+  process.exit(1);
 }
 async function handleList() {
   const { dir, port, tls: tls2 } = await discoverState();
@@ -1384,9 +1450,9 @@ ${colors_default.bold("Options:")}
   --help, -h             Show this help
 
 ${colors_default.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)
+  portless get backend                  # -> https://backend.localhost
+  portless get backend                  # in worktree -> https://auth.backend.localhost
+  portless get backend --no-worktree    # -> https://backend.localhost (skip worktree)
 `);
     process.exit(0);
   }
@@ -1430,8 +1496,8 @@ ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless alias <name> <port> --force")} Override existing route
 
 ${colors_default.bold("Examples:")}
-  portless alias my-postgres 5432     # -> http://my-postgres.localhost:1355
-  portless alias redis 6379           # -> http://redis.localhost:1355
+  portless alias my-postgres 5432     # -> https://my-postgres.localhost
+  portless alias redis 6379           # -> https://redis.localhost
   portless alias --remove my-postgres # Remove the alias
 `);
     process.exit(0);
@@ -1488,8 +1554,8 @@ Safari relies on the system DNS resolver, which may not handle .localhost
 subdomains. This command adds entries to ${HOSTS_DISPLAY} as a workaround.
 
 ${colors_default.bold("Usage:")}
-  ${colors_default.cyan(`${SUDO_PREFIX}portless hosts sync`)}    Add current routes to ${HOSTS_DISPLAY}
-  ${colors_default.cyan(`${SUDO_PREFIX}portless hosts clean`)}   Remove portless entries from ${HOSTS_DISPLAY}
+  ${colors_default.cyan("portless hosts sync")}    Add current routes to ${HOSTS_DISPLAY}
+  ${colors_default.cyan("portless hosts clean")}   Remove portless entries from ${HOSTS_DISPLAY}
 
 ${colors_default.bold("Auto-sync:")}
   Auto-enabled for custom TLDs (e.g. --tld test). For .localhost, set
@@ -1500,33 +1566,44 @@ ${colors_default.bold("Auto-sync:")}
   if (args[1] === "clean") {
     if (cleanHostsFile()) {
       console.log(colors_default.green(`Removed portless entries from ${HOSTS_DISPLAY}.`));
-    } else {
-      console.error(
-        colors_default.red(
-          `Failed to update ${HOSTS_DISPLAY}${isWindows ? " (run as Administrator)." : " (requires sudo)."}`
+      return;
+    }
+    if (!isWindows && process.getuid?.() !== 0) {
+      console.log(
+        colors_default.yellow(
+          `Writing to ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`
         )
       );
-      console.error(colors_default.cyan(`  ${SUDO_PREFIX}portless hosts clean`));
-      process.exit(1);
+      const result = spawnSync(
+        "sudo",
+        ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "hosts", "clean"],
+        {
+          stdio: "inherit",
+          timeout: SUDO_SPAWN_TIMEOUT_MS
+        }
+      );
+      if (result.status === 0) return;
     }
+    console.error(
+      colors_default.red(`Failed to update ${HOSTS_DISPLAY}${isWindows ? " (run as Administrator)." : "."}`)
+    );
+    process.exit(1);
     return;
   }
   if (!args[1]) {
     console.log(`
 ${colors_default.bold("Usage: portless hosts <command>")}
 
-  ${colors_default.cyan(`${SUDO_PREFIX}portless hosts sync`)}    Add current routes to ${HOSTS_DISPLAY}
-  ${colors_default.cyan(`${SUDO_PREFIX}portless hosts clean`)}   Remove portless entries from ${HOSTS_DISPLAY}
+  ${colors_default.cyan("portless hosts sync")}    Add current routes to ${HOSTS_DISPLAY}
+  ${colors_default.cyan("portless hosts clean")}   Remove portless entries from ${HOSTS_DISPLAY}
 `);
     process.exit(0);
   }
   if (args[1] !== "sync") {
     console.error(colors_default.red(`Error: Unknown hosts subcommand "${args[1]}".`));
     console.error(colors_default.blue("Usage:"));
-    console.error(
-      colors_default.cyan(`  ${SUDO_PREFIX}portless hosts sync    # Add routes to ${HOSTS_DISPLAY}`)
-    );
-    console.error(colors_default.cyan(`  ${SUDO_PREFIX}portless hosts clean   # Remove portless entries`));
+    console.error(colors_default.cyan(`  portless hosts sync    # Add routes to ${HOSTS_DISPLAY}`));
+    console.error(colors_default.cyan("  portless hosts clean   # Remove portless entries"));
     process.exit(1);
   }
   const { dir } = await discoverState();
@@ -1544,23 +1621,53 @@ ${colors_default.bold("Usage: portless hosts <command>")}
     for (const h of hostnames) {
       console.log(colors_default.cyan(`  127.0.0.1 ${h}`));
     }
-  } else {
-    console.error(
-      colors_default.red(
-        `Failed to update ${HOSTS_DISPLAY}${isWindows ? " (run as Administrator)." : " (requires sudo)."}`
-      )
+    return;
+  }
+  if (!isWindows && process.getuid?.() !== 0) {
+    console.log(
+      colors_default.yellow(`Writing to ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`)
     );
-    console.error(colors_default.cyan(`  ${SUDO_PREFIX}portless hosts sync`));
-    process.exit(1);
+    const result = spawnSync(
+      "sudo",
+      ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "hosts", "sync"],
+      {
+        stdio: "inherit",
+        timeout: SUDO_SPAWN_TIMEOUT_MS
+      }
+    );
+    if (result.status === 0) return;
   }
+  console.error(
+    colors_default.red(`Failed to update ${HOSTS_DISPLAY}${isWindows ? " (run as Administrator)." : "."}`)
+  );
+  process.exit(1);
 }
 async function handleProxy(args) {
   if (args[1] === "stop") {
-    const { dir, port, tls: tls2 } = await discoverState();
-    const store2 = new RouteStore(dir, {
-      onWarning: (msg) => console.warn(colors_default.yellow(msg))
-    });
-    await stopProxy(store2, port, tls2);
+    let explicitPort;
+    const portIdx = args.indexOf("--port") !== -1 ? args.indexOf("--port") : args.indexOf("-p");
+    if (portIdx !== -1) {
+      const portValue = args[portIdx + 1];
+      if (portValue && !portValue.startsWith("-")) {
+        const parsed = parseInt(portValue, 10);
+        if (!isNaN(parsed) && parsed >= 1 && parsed <= 65535) {
+          explicitPort = parsed;
+        }
+      }
+    }
+    if (explicitPort !== void 0) {
+      const dir = resolveStateDir(explicitPort);
+      const store2 = new RouteStore(dir, {
+        onWarning: (msg) => console.warn(colors_default.yellow(msg))
+      });
+      await stopProxy(store2, explicitPort, false);
+    } else {
+      const { dir, port, tls: tls2 } = await discoverState();
+      const store2 = new RouteStore(dir, {
+        onWarning: (msg) => console.warn(colors_default.yellow(msg))
+      });
+      await stopProxy(store2, port, tls2);
+    }
     return;
   }
   const isProxyHelp = args[1] === "--help" || args[1] === "-h";
@@ -1569,10 +1676,10 @@ async function handleProxy(args) {
 ${colors_default.bold("portless proxy")} - Manage the portless proxy server.
 
 ${colors_default.bold("Usage:")}
-  ${colors_default.cyan("portless proxy start")}                Start the proxy (daemon)
-  ${colors_default.cyan("portless proxy start --https")}        Start with HTTP/2 + TLS
+  ${colors_default.cyan("portless proxy start")}                Start the HTTPS proxy on port 443 (daemon)
+  ${colors_default.cyan("portless proxy start --no-tls")}       Start without HTTPS (port 80)
   ${colors_default.cyan("portless proxy start --foreground")}   Start in foreground (for debugging)
-  ${colors_default.cyan("portless proxy start -p 80")}          Start on port 80 (requires sudo)
+  ${colors_default.cyan("portless proxy start -p 1355")}        Start on a custom port (no sudo)
   ${colors_default.cyan("portless proxy start --tld test")}     Use .test instead of .localhost
   ${colors_default.cyan("portless proxy start --wildcard")}     Allow unregistered subdomains to fall back to parent
   ${colors_default.cyan("portless proxy stop")}                 Stop the proxy
@@ -1580,27 +1687,8 @@ ${colors_default.bold("Usage:")}
     process.exit(isProxyHelp || !args[1] ? 0 : 1);
   }
   const isForeground = args.includes("--foreground");
-  let proxyPort = getDefaultPort();
-  let portFlagIndex = args.indexOf("--port");
-  if (portFlagIndex === -1) portFlagIndex = args.indexOf("-p");
-  if (portFlagIndex !== -1) {
-    const portValue = args[portFlagIndex + 1];
-    if (!portValue || portValue.startsWith("-")) {
-      console.error(colors_default.red("Error: --port / -p requires a port number."));
-      console.error(colors_default.blue("Usage:"));
-      console.error(colors_default.cyan("  portless proxy start -p 8080"));
-      process.exit(1);
-    }
-    proxyPort = parseInt(portValue, 10);
-    if (isNaN(proxyPort) || proxyPort < 1 || proxyPort > 65535) {
-      console.error(colors_default.red(`Error: Invalid port number: ${portValue}`));
-      console.error(colors_default.blue("Port must be between 1 and 65535."));
-      process.exit(1);
-    }
-  }
-  const hasNoTls = args.includes("--no-tls");
-  const hasHttpsFlag = args.includes("--https");
-  const wantHttps = !hasNoTls && (hasHttpsFlag || isHttpsEnvEnabled());
+  const hasNoTls = args.includes("--no-tls") || isHttpsEnvDisabled();
+  const wantHttps = !hasNoTls;
   let customCertPath = null;
   let customKeyPath = null;
   const certIdx = args.indexOf("--cert");
@@ -1623,6 +1711,27 @@ ${colors_default.bold("Usage:")}
     console.error(colors_default.red("Error: --cert and --key must be used together."));
     process.exit(1);
   }
+  const useHttps = wantHttps || !!(customCertPath && customKeyPath);
+  let hasExplicitPort = false;
+  let proxyPort = getDefaultPort(useHttps);
+  let portFlagIndex = args.indexOf("--port");
+  if (portFlagIndex === -1) portFlagIndex = args.indexOf("-p");
+  if (portFlagIndex !== -1) {
+    const portValue = args[portFlagIndex + 1];
+    if (!portValue || portValue.startsWith("-")) {
+      console.error(colors_default.red("Error: --port / -p requires a port number."));
+      console.error(colors_default.blue("Usage:"));
+      console.error(colors_default.cyan("  portless proxy start -p 8080"));
+      process.exit(1);
+    }
+    proxyPort = parseInt(portValue, 10);
+    if (isNaN(proxyPort) || proxyPort < 1 || proxyPort > 65535) {
+      console.error(colors_default.red(`Error: Invalid port number: ${portValue}`));
+      console.error(colors_default.blue("Port must be between 1 and 65535."));
+      process.exit(1);
+    }
+    hasExplicitPort = true;
+  }
   let tld;
   try {
     tld = getDefaultTld();
@@ -1646,7 +1755,7 @@ ${colors_default.bold("Usage:")}
   }
   const riskyReason = RISKY_TLDS.get(tld);
   if (riskyReason) {
-    console.warn(colors_default.yellow(`Warning: .${tld} -- ${riskyReason}`));
+    console.warn(colors_default.yellow(`Warning: .${tld}: ${riskyReason}`));
   }
   const syncDisabled = process.env.PORTLESS_SYNC_HOSTS === "0" || process.env.PORTLESS_SYNC_HOSTS === "false";
   if (tld !== DEFAULT_TLD && syncDisabled) {
@@ -1656,36 +1765,96 @@ ${colors_default.bold("Usage:")}
       )
     );
     console.warn(colors_default.yellow("Hosts sync is disabled. To add entries manually, run:"));
-    console.warn(colors_default.cyan(`  ${SUDO_PREFIX}portless hosts sync`));
+    console.warn(colors_default.cyan("  portless hosts sync"));
   }
   const useWildcard = args.includes("--wildcard") || isWildcardEnvEnabled();
-  const useHttps = wantHttps || !!(customCertPath && customKeyPath);
-  const stateDir = resolveStateDir(proxyPort);
-  const store = new RouteStore(stateDir, {
+  let stateDir = resolveStateDir(proxyPort);
+  let store = new RouteStore(stateDir, {
     onWarning: (msg) => console.warn(colors_default.yellow(msg))
   });
   if (await isProxyRunning(proxyPort)) {
     if (isForeground) {
       return;
     }
-    const needsSudo = !isWindows && proxyPort < PRIVILEGED_PORT_THRESHOLD;
-    const sudoPrefix = needsSudo ? "sudo " : "";
-    const portFlag = proxyPort !== getDefaultPort() ? ` -p ${proxyPort}` : "";
+    const portFlag = proxyPort !== getProtocolPort(useHttps) ? ` -p ${proxyPort}` : "";
     console.log(colors_default.yellow(`Proxy is already running on port ${proxyPort}.`));
     console.log(
-      colors_default.blue(
-        `To restart: ${sudoPrefix}portless proxy stop${portFlag} && ${sudoPrefix}portless proxy start${portFlag}`
-      )
+      colors_default.blue(`To restart: portless proxy stop${portFlag} && portless proxy start${portFlag}`)
     );
     return;
   }
   if (!isWindows && proxyPort < PRIVILEGED_PORT_THRESHOLD && (process.getuid?.() ?? -1) !== 0) {
-    console.error(colors_default.red(`Error: Port ${proxyPort} requires sudo.`));
-    console.error(colors_default.blue("Either run with sudo:"));
-    console.error(colors_default.cyan("  sudo portless proxy start -p 80"));
-    console.error(colors_default.blue("Or use the default port (no sudo needed):"));
-    console.error(colors_default.cyan("  portless proxy start"));
-    process.exit(1);
+    const baseArgs = [
+      process.execPath,
+      getEntryScript(),
+      "proxy",
+      "start",
+      "-p",
+      String(proxyPort)
+    ];
+    const optionalFlags = [];
+    if (hasNoTls) optionalFlags.push("--no-tls");
+    if (tld !== DEFAULT_TLD) optionalFlags.push("--tld", tld);
+    if (useWildcard) optionalFlags.push("--wildcard");
+    if (isForeground) optionalFlags.push("--foreground");
+    if (customCertPath && customKeyPath)
+      optionalFlags.push("--cert", customCertPath, "--key", customKeyPath);
+    const startArgs = [...baseArgs, ...optionalFlags];
+    const extraFlags = optionalFlags.map((a) => ` ${a}`).join("");
+    console.log(
+      colors_default.yellow(`Port ${proxyPort} requires elevated privileges. Requesting sudo...`)
+    );
+    if (!hasExplicitPort) {
+      console.log(
+        colors_default.gray(
+          `(To skip sudo, use an unprivileged port: portless proxy start -p ${FALLBACK_PROXY_PORT}${extraFlags})`
+        )
+      );
+    }
+    const result = spawnSync("sudo", ["env", ...collectPortlessEnvArgs(), ...startArgs], {
+      stdio: "inherit",
+      timeout: SUDO_SPAWN_TIMEOUT_MS
+    });
+    if (result.status === 0) {
+      if (!isForeground) {
+        if (await waitForProxy(proxyPort)) {
+          console.log(colors_default.green(`Proxy started on port ${proxyPort}.`));
+        } else {
+          console.error(colors_default.red("Proxy process started but is not responding."));
+          const logPath2 = path3.join(resolveStateDir(proxyPort), "proxy.log");
+          if (fs3.existsSync(logPath2)) {
+            console.error(colors_default.gray(`Logs: ${logPath2}`));
+          }
+        }
+      }
+      return;
+    }
+    if (result.signal) {
+      process.exit(1);
+    }
+    if (!hasExplicitPort) {
+      proxyPort = FALLBACK_PROXY_PORT;
+      console.log(colors_default.yellow(`Falling back to port ${proxyPort}.`));
+      console.log(
+        colors_default.blue(`For clean URLs without port numbers, re-run and accept the sudo prompt:`)
+      );
+      console.log(colors_default.cyan(`  portless proxy start${extraFlags}`));
+      if (await isProxyRunning(proxyPort)) {
+        console.log(colors_default.yellow(`Proxy is already running on port ${proxyPort}.`));
+        return;
+      }
+      stateDir = resolveStateDir(proxyPort);
+      store = new RouteStore(stateDir, {
+        onWarning: (msg) => console.warn(colors_default.yellow(msg))
+      });
+    } else {
+      console.error(
+        colors_default.red(`Error: Port ${proxyPort} requires elevated privileges and sudo failed.`)
+      );
+      console.error(colors_default.blue("Try again (portless will prompt for sudo):"));
+      console.error(colors_default.cyan(`  portless proxy start -p ${proxyPort}${extraFlags}`));
+      process.exit(1);
+    }
   }
   let tlsOptions;
   if (useHttps) {
@@ -1703,7 +1872,9 @@ ${colors_default.bold("Usage:")}
         }
         if (!keyStr.match(/-----BEGIN [\w\s]*PRIVATE KEY-----/)) {
           console.error(colors_default.red(`Error: ${customKeyPath} is not a valid PEM private key.`));
-          console.error(colors_default.gray("Expected a file starting with -----BEGIN ...PRIVATE KEY-----"));
+          console.error(
+            colors_default.gray("Expected a file starting with -----BEGIN ...PRIVATE KEY-----")
+          );
           process.exit(1);
         }
         tlsOptions = { cert, key };
@@ -1759,16 +1930,22 @@ ${colors_default.bold("Usage:")}
     } catch {
     }
     fixOwnership(logPath);
-    const daemonArgs = [process.argv[1], "proxy", "start", "--foreground"];
-    if (portFlagIndex !== -1) {
-      daemonArgs.push("--port", proxyPort.toString());
-    }
+    const daemonArgs = [
+      getEntryScript(),
+      "proxy",
+      "start",
+      "--foreground",
+      "--port",
+      proxyPort.toString()
+    ];
     if (useHttps) {
       if (customCertPath && customKeyPath) {
         daemonArgs.push("--cert", customCertPath, "--key", customKeyPath);
       } else {
         daemonArgs.push("--https");
       }
+    } else {
+      daemonArgs.push("--no-tls");
     }
     if (tld !== DEFAULT_TLD) {
       daemonArgs.push("--tld", tld);
@@ -1789,8 +1966,7 @@ ${colors_default.bold("Usage:")}
   if (!await waitForProxy(proxyPort, void 0, void 0, useHttps)) {
     console.error(colors_default.red("Proxy failed to start (timed out waiting for it to listen)."));
     console.error(colors_default.blue("Try starting the proxy in the foreground to see the error:"));
-    const needsSudo = !isWindows && proxyPort < PRIVILEGED_PORT_THRESHOLD;
-    console.error(colors_default.cyan(`  ${needsSudo ? "sudo " : ""}portless proxy start --foreground`));
+    console.error(colors_default.cyan("  portless proxy start --foreground"));
     if (fs3.existsSync(logPath)) {
       console.error(colors_default.gray(`Logs: ${logPath}`));
     }
@@ -1878,10 +2054,11 @@ async function main() {
   const args = process.argv.slice(2);
   const isNpx = process.env.npm_command === "exec" && !process.env.npm_lifecycle_event;
   const isPnpmDlx = !!process.env.PNPM_SCRIPT_SRC_DIR && !process.env.npm_lifecycle_event;
-  if (isNpx || isPnpmDlx) {
+  if ((isNpx || isPnpmDlx) && !isLocallyInstalled()) {
     console.error(colors_default.red("Error: portless should not be run via npx or pnpm dlx."));
-    console.error(colors_default.blue("Install globally instead:"));
+    console.error(colors_default.blue("Install globally or as a project dependency:"));
     console.error(colors_default.cyan("  npm install -g portless"));
+    console.error(colors_default.cyan("  npm install -D portless"));
     process.exit(1);
   }
   if (args[0] === "--name") {