portless-studio 0.1.1 → 0.1.3

package/README.md

@@ -22,7 +22,8 @@ The screenshots use the built-in sample data (`?demo`), not a real machine.
 
 ## Install
 
-Requires Node 22 or later.
+Requirements: Node 22 or later on Linux, macOS or Windows. portless is installed for you if it is
+missing.
 
 To try it, run it straight from npm:
 
@@ -40,18 +41,8 @@ portless-studio init
 The login service starts Studio from the files npm installed. Run through `npx`, those files sit in
 npm's cache, which npm can clear at any time, and then Studio stops starting at login.
 
-To update, install the latest version and restart Studio:
-
-```bash
-npm i -g portless-studio@latest
-```
-
-To remove it, undo the setup first, then remove the package:
-
-```bash
-portless-studio uninstall
-npm rm -g portless-studio
-```
+To update, install the latest version and restart Studio with `npm i -g portless-studio@latest`.
+To remove it, run `portless-studio uninstall`, then `npm rm -g portless-studio`.
 
 ## Quick start
 
@@ -63,61 +54,52 @@ npm rm -g portless-studio
 - Starts the portless proxy on port 1355 over HTTP, which needs no password, certificate or extra
   tool on macOS, Windows or Linux, and can set Studio to start when you log in.
 
-`init --yes` accepts every default without asking. After that, `portless-studio` starts
-Studio at `http://127.0.0.1:4949`, registers it in portless as `studio` and opens your browser.
-Your apps open at names like `http://web.myapp.localhost:1355`: Chrome, Edge and Firefox send
-every `*.localhost` name to your own machine, with no hosts file and no DNS setup.
+Then `portless-studio` starts Studio at `http://127.0.0.1:4949`, registers it in portless as
+`studio` and opens your browser. Your apps open at names like `http://web.myapp.localhost:1355`:
+Chrome, Edge and Firefox send every `*.localhost` name to your own machine, with no hosts file and
+no DNS setup. Turn on Short URLs in Settings to drop the `:1355` (`http://web.myapp.localhost`)
+where your system lets you listen on port 80; see
+[troubleshooting](docs/troubleshooting.md#names-have-1355-and-i-want-port-80).
 
-To try the page without portless, start Studio and open `http://127.0.0.1:4949/?demo` for sample
-data, or `?demo&noportless` to walk through the install flow with a fake install.
+[Getting started](docs/getting-started.md) walks through the first five minutes: naming a dev
+server, naming a port by hand, running a command in a Studio terminal and turning on auto mode.
+To try the page without portless, open `http://127.0.0.1:4949/?demo` for sample data.
 
 ## What it does
 
 - **Live list** of portless routes: name, URL, port, app or alias, uptime and any Tailscale, ngrok
   or Cloudflare tunnel. It updates as soon as a route appears or goes away.
 - **Detected ports:** listening ports that answer HTTP but have no name yet, with the process, the
-  project folder and a suggested name. Name one, name them all, or ignore one.
-- **Auto mode** (off by default): every new dev server gets its suggested name by itself, once
-  it has shown up unnamed in two scans in a row, so a server started with `portless <name>` keeps
-  the name portless gives it. Names auto mode gave are removed 10 minutes after their port closes.
+  project folder and a suggested name. Name one, name them all, or ignore one. Ports a running
+  Docker container publishes show here too.
+- **Auto mode** (off by default): every new dev server gets its suggested name by itself. Names
+  auto mode gave are removed 10 minutes after their port closes.
 - **Name a port** that portless did not start, such as a database in Docker (`db` gives
   `db.localhost`). Rename or remove those names later.
 - **Where each server runs:** every row shows the git branch, the linked worktree and the project
-  folder. A route whose server is down keeps the last place it ran.
-- **Views:** group by project, worktree, kind or status, or into your own groups; sort, and
-  filter by kind, status or project from the Filter button; save the combination as a named view
-  and pick the one that opens by default.
+  folder.
+- **Views:** group by project, worktree, kind or status, or into your own groups; filter, sort and
+  save the combination as a named view.
 - **Terminals:** run a command per project inside Studio and watch its output in a panel. You, the
-  CLI and your AI agents drive the same terminals. See [docs/terminals.md](docs/terminals.md).
+  CLI and your AI agents drive the same terminals.
 - **Agents:** an MCP server lets Claude Code, Cursor and other agents list, name and stop dev
-  servers and run commands in Studio terminals. See [docs/mcp.md](docs/mcp.md).
-- **Open with:** right-click a row to open its folder in an editor found on your machine (VS Code,
-  Cursor, Zed, WebStorm, IntelliJ IDEA, Sublime Text), reveal it in the file manager or copy its
-  path. Add your own apps in Settings.
-- **Health:** each route's dot says whether its port answers. The Health panel and
-  `portless-studio doctor` find a proxy left running as root, two proxies at once, an untrusted
-  certificate or a taken port, and give the fix.
-- **Proxy and Studio control:** start, stop or restart the portless proxy, and stop or restart
-  Studio, from the page.
-- **Stop a dev server** from its row, after a confirmation. Only your own processes on a port
-  Studio shows.
-- **Project icons:** the favicon the server serves, else one in the project folder, else the
-  project's initials. Set an emoji or an image per project in Settings.
-- **Notifications** in the page when a server is detected or named, and optionally from the
-  operating system.
-- **Install portless** from the page when the `portless` command is missing.
+  servers and run commands in Studio terminals.
+- **Health:** each route's dot says whether its port answers, and `portless-studio doctor` finds a
+  proxy left running as root, two proxies at once, an untrusted certificate or a taken port, and
+  gives the fix.
 - **Keyboard first:** every action has a key, `?` lists them and `Ctrl+K` (`Cmd+K`) runs any of
   them by name.
 
-## How naming works
+Also: start, stop or restart the proxy and Studio from the page, stop a dev server from its row,
+open a project in your editor, project icons, and notifications in the page or from the operating
+system.
+
+## Naming
 
 A suggested name says what the work is, then the app, then the repository. The package
 `@acme/web` in the `acme-monorepo` folder on the branch `feat/ED-1234-add-x` gets
-`ed-1234.web.acme`, so two worktrees of one repository get different names. That is the order
-portless uses for worktrees, `<branch>.<name>.localhost`.
-
-Change it with `nameTemplate`, for example `{ticket}.{repo}` or `{package}-{port}`.
-[docs/naming.md](docs/naming.md) lists every token and how empty or repeated parts are dropped.
+`ed-1234.web.acme`, so two worktrees of one repository get different names. Change the pattern
+with `nameTemplate`; [docs/naming.md](docs/naming.md) lists every token.
 
 Anything that names a route through the portless CLI also shows up in Studio:
 
@@ -126,177 +108,42 @@ portless web.myapp pnpm dev       # a dev server, at web.myapp.localhost
 portless alias db.myapp 5432      # a port something else opened, at db.myapp.localhost
 ```
 
-## Agents and MCP
-
-`portless-studio mcp` is an [MCP](https://modelcontextprotocol.io) server on stdio. It talks to the
-Studio already running, so whatever an agent changes shows up in the page at once. For Claude Code:
+## Agents and terminals
 
 ```bash
 claude mcp add --scope user portless-studio -- npx -y portless-studio mcp
+portless-studio run -- pnpm dev
 ```
 
-[docs/mcp.md](docs/mcp.md) has the setup for Cursor and other clients, the list of tools, and
-instructions to paste into your agent so it names dev servers after the ticket or pull request.
-`portless-studio list --json` and `doctor --json` give the same data to scripts.
+The first line connects Claude Code to Studio's MCP server. The second runs a dev server in a
+Studio terminal, prints its output in your shell and names the port it opens.
+[docs/agents.md](docs/agents.md) shows how to keep agents in sync with Studio, including
+instructions to paste and Claude Code hooks; [docs/mcp.md](docs/mcp.md) has the setup for other
+clients and [docs/terminals.md](docs/terminals.md) covers the terminal panel.
 
-## Terminals
+## Documentation
 
-```bash
-portless-studio run -- pnpm dev
-```
+- [Getting started](docs/getting-started.md) and [Troubleshooting](docs/troubleshooting.md)
+- [Command line](docs/cli.md), [Configuration](docs/configuration.md) and
+  [Keyboard shortcuts](docs/keyboard-shortcuts.md)
+- [Naming](docs/naming.md), [Terminals](docs/terminals.md) and
+  [Linux, macOS and Windows](docs/platforms.md)
+- [Agents](docs/agents.md) and [MCP server](docs/mcp.md)
+- [Every page, with one line each](docs/README.md)
+
+## How it relates to portless
 
-`run` starts the command in a Studio terminal in the current folder, prints its output here,
-names the first port it opens and stops it on Ctrl+C. The terminal stays visible in the page.
-[docs/terminals.md](docs/terminals.md) covers the panel, the CLI and the security rules.
-
-## Platforms
-
-Studio runs on Linux, macOS and Windows with Node 22 or later and installs nothing beyond portless. Each
-feature uses tools the system already has (`/proc` on Linux, `lsof` on macOS, `netstat` and
-PowerShell on Windows). [docs/platforms.md](docs/platforms.md) says what each system uses and what
-does not work the same everywhere.
-
-## Commands
-
-| Command | What it does |
-| --- | --- |
-| `portless-studio` | Starts Studio with the settings from the config file. |
-| `portless-studio init [--yes]` | The setup above. Safe to run again. |
-| `portless-studio uninstall [--yes]` | Undoes the setup: removes the login service, the names auto mode gave and the `studio` name, and stops the proxy if Studio started it. Names you or an agent gave stay. Asks before deleting the settings folder. |
-| `portless-studio service install` | Starts Studio when you log in: a systemd user unit on Linux, a LaunchAgent on macOS, a script in the Startup folder on Windows. |
-| `portless-studio service uninstall` | Undoes `service install`. |
-| `portless-studio service status` | Says whether the login service is installed and running. |
-| `portless-studio config [--edit] [--json]` | Prints the config file path and contents, or opens it in `$EDITOR`. |
-| `portless-studio doctor [--json]` | Checks portless, the proxy, the certificate, Studio's port and the login service, and prints the fix for each problem. Exits with 1 when something fails. |
-| `portless-studio list [--json]` | Lists named routes and ports without a name. |
-| `portless-studio mcp` | Runs the MCP server on stdio for AI agents. |
-| `portless-studio run [--name <name>] [--cwd <dir>] -- <command...>` | Runs a command in a Studio terminal and names the port it opens. |
-| `portless-studio open [target]` | Brings Studio to the front showing a route, project, terminal id or `port:<n>`. |
-
-| Flag | Effect |
-| --- | --- |
-| `--port <n>` | Port for the dashboard on 127.0.0.1. Default: `port` in the config, 4949. `0` picks a free one. |
-| `--no-open` | Do not open the browser. |
-| `--no-register` | Do not register the `studio` name in portless. |
-| `-y`, `--yes` | With `init` and `uninstall`: accept every default. |
-| `-h`, `--help` | Show the help. |
-| `-v`, `--version` | Show the version. |
-
-| Environment variable | What it does |
-| --- | --- |
-| `PORTLESS_STUDIO_CONFIG` | Path of the config file. |
-| `PORTLESS_STATE_DIR` | portless state folder. Default `~/.portless`. |
-| `PORTLESS_BIN` | portless binary used to create and remove names. Default `portless`. |
-| `PORTLESS_STUDIO_URL` | Studio that `mcp`, `list`, `run` and `open` talk to. Default `http://127.0.0.1:<port>`. |
-| `PORTLESS_STUDIO_NO_UPDATE_CHECK` | `1` turns the daily update check off, whatever the config says. |
-| `EDITOR` | Editor that `config --edit` opens. |
-
-## Config file
-
-Settings live in one JSON file: `~/.config/portless-studio/config.json` on Linux and macOS (or
-under `$XDG_CONFIG_HOME`), `%APPDATA%\portless-studio\config.json` on Windows. `portless-studio
-config` prints the path. Edit it by hand or from the Settings panel; a running Studio picks up the
-changes without a restart. Missing fields take their default.
-
-| Field | Default | What it does |
-| --- | --- | --- |
-| `port` | `4949` | Port Studio listens on, on 127.0.0.1. |
-| `autoName` | `false` | Gives every new dev server a portless name automatically. |
-| `autoRemoveAfterMinutes` | `10` | Minutes a name auto mode gave survives after its port closes. `0` keeps them. |
-| `openBrowser` | `true` | Opens the browser when Studio starts. |
-| `registerStudioAlias` | `true` | Registers Studio itself in portless as `studio`. |
-| `startProxy` | `true` | Starts the portless proxy when Studio starts and it is not running. |
-| `proxyPort` | `1355` | Port of that proxy. 1355 needs no administrator rights; 443 removes the port from URLs. |
-| `proxyHttps` | `false` | Serves the names over HTTPS. See the FAQ. |
-| `scanIntervalMs` | `3000` | How often Studio looks for new listening ports, in milliseconds (at least 1000). |
-| `ignoredPorts` | `[]` | Ports never shown as detected and never named automatically. |
-| `ignoredProcesses` | editors, chat apps, browsers | Process names whose ports are never shown. |
-| `views` | one view, `All`, grouped by project | Saved views: grouping, sort, filters and custom groups. |
-| `defaultViewId` | `"all"` | The view the page opens with. |
-| `favorites` | `[]` | Routes pinned above every group, by name or as `"port:3000"`. |
-| `desktopNotifications` | `false` | Notifies from an open Studio tab while it is in the background. |
-| `systemNotifications` | `false` | Asks the operating system to notify when no Studio tab is open. |
-| `nameTemplate` | `"{work}.{package}.{repo}"` | How suggested names are built. See [docs/naming.md](docs/naming.md). |
-| `projectIcons` | `{}` | Icon per project: an emoji, an http(s) image URL or a `data:image` URL. |
-| `checkForUpdates` | `true` | Once a day, asks npm whether a newer portless-studio exists. See "Update notice" below. |
-
-The `--port`, `--no-open` and `--no-register` flags win over the file for one run. Apps you add to
-the Open with menu live in `open-with.json` next to the config file.
-
-### Update notice
-
-Once a day Studio asks the npm registry for the latest version of portless-studio. When a newer
-one exists, it prints one line on start and shows a banner in the page with the command to update;
-dismissing the banner hides it until the next version. The request is a plain
-`GET https://registry.npmjs.org/portless-studio/latest`: Studio sends nothing about your machine,
-your projects or your routes. It gives up after 3 seconds and stays quiet when you are offline,
-and it keeps the time of the last check in `update-check.json` next to the config file. It never
-runs when the `CI` variable is set. Turn it off with `checkForUpdates: false`, the Settings
-switch, or `PORTLESS_STUDIO_NO_UPDATE_CHECK=1`.
-
-## Keyboard shortcuts
-
-| Keys | Action |
-| --- | --- |
-| `j` / `↓`, `k` / `↑` | Next and previous row |
-| `Home`, `End` | First and last row |
-| `/` | Search routes |
-| `Enter` or `o` | Open the selected route |
-| `c` | Copy its URL |
-| `r` | Rename an alias |
-| `Delete` or `Backspace` | Remove an alias |
-| `f` | Pin or unpin as favorite |
-| `.` or `Shift+F10` | Open with, copy path and more |
-| `t` | Open a terminal in its folder |
-| `n` | Name a port |
-| `v` / `Shift+V` | Next view / open the view menu |
-| `Shift+F` | Open the filters |
-| `[`, `]` | Collapse or expand all groups |
-| `Ctrl+K` / `Cmd+K` | Command menu |
-| `,` | Settings |
-| `?` | All keyboard shortcuts |
-| `Esc` | Close a dialog or cancel |
+Studio is an independent project, not part of portless and not made by its authors. It reads the
+state portless keeps in `~/.portless` and names routes through the `portless` command, so anything
+you or an agent do with portless shows up in Studio, and Studio never changes how portless works.
 
 ## Security
 
-Studio is a local tool and only listens on `127.0.0.1`. It rejects requests whose `Host` or
-`Origin` is not local, so other websites open in your browser cannot read your routes or call the
-API. Every change (naming, removing, installing portless, controlling the proxy or Studio, stopping
-a dev server, running terminals) also needs a token that changes on every run. The page reads it from
-Studio, and browsers only let pages served by Studio itself read it. The portless install always runs the same fixed command.
-A dev server can be stopped only when it belongs to your user and listens on a port Studio shows,
-and Studio never runs a command that needs sudo. See [SECURITY.md](SECURITY.md) to report a
-problem.
-
-## FAQ
-
-**Safari does not open `*.localhost` names.** Safari does not always send `.localhost` names to
-your machine. Open Studio at `http://127.0.0.1:4949` and each app at `http://127.0.0.1:<its port>`,
-or use Chrome, Edge or Firefox.
-
-**Why HTTP on port 1355, and how do I get HTTPS or port 443?** Port 1355 needs no administrator
-rights on any system, and browsers treat plain HTTP on a `.localhost` name as a secure context, so
-most apps work as they would on HTTPS. For URLs without a port, set `proxyPort` to `443`; on Linux
-that needs sudo once to start the proxy. For HTTPS, set `proxyHttps` to `true` and trust the
-portless certificate: `portless-studio doctor` prints the exact command for your system, and the
-Health panel shows it too.
-
-**Does it work on Windows?** Yes, with Node 22 or later and PowerShell 5 (included in Windows 10 and 11).
-Ports come from `netstat`, process details from PowerShell, and start at login uses a hidden
-script in the Startup folder. Windows has no service manager Studio can ask, so the page can stop
-Studio but not restart it, and the doctor only sees the proxy portless records.
-[docs/platforms.md](docs/platforms.md) lists every difference.
-
-**How does it relate to portless?** Studio is an independent project, not part of portless and not
-made by its authors. It reads the state portless keeps in `~/.portless` and names routes through
-the `portless` command, so anything you or an agent do with portless shows up in Studio, and
-Studio never changes how portless works.
-
-**How do I remove it?** Run `portless-studio uninstall` (or `npx portless-studio uninstall` if you
-never installed it globally). It removes the login service, the names auto mode gave and the
-`studio` name, stops the proxy if Studio started it, and asks before deleting the settings folder.
-Then remove the package with `npm rm -g portless-studio`. portless itself stays installed; remove it with
-`npm uninstall -g portless`.
+Studio only listens on `127.0.0.1` and rejects requests whose `Host` or `Origin` is not local, so
+other websites open in your browser cannot read your routes or call the API. Every change also
+needs a token that changes on every run and that only Studio's own page can read. A dev server can
+be stopped only when it belongs to your user, and Studio never runs a command that needs sudo.
+See [SECURITY.md](SECURITY.md) to report a problem.
 
 ## Development
 
@@ -306,16 +153,11 @@ cd portless-studio
 pnpm install
 pnpm dev          # API on :4949 and the web app with hot reload on :5173
 pnpm test         # unit and component tests
-pnpm typecheck
-pnpm check        # lint and format check
-pnpm build        # builds dist/, then `pnpm start` runs it
-pnpm smoke        # starts the built CLI on a free port and checks the API answers
 ```
 
-The code is split so the web app can talk to another backend later: see
-[docs/architecture.md](docs/architecture.md). Conventions are in
-[docs/conventions.md](docs/conventions.md), and [CONTRIBUTING.md](CONTRIBUTING.md) covers pull
-requests.
+[CONTRIBUTING.md](CONTRIBUTING.md) covers the checks to run and pull requests,
+[docs/architecture.md](docs/architecture.md) the layers and
+[docs/conventions.md](docs/conventions.md) the code conventions.
 
 ## License
 

package/dist/cli/cli-args.js

@@ -17,6 +17,10 @@ Usage:
                                       what is wrong (exit code 1 when something fails)
   portless-studio list [--json]       List named routes and ports without a name, from the running
                                       Studio (or read directly when it is not running)
+  portless-studio env [--prefix P] [--strip S] [--direct] [--json] [name...]
+                                      Print KEY=url lines for a .env file, one per route
+                                      (api.acme -> API_ACME_URL); a name also picks its *.name
+                                      routes (docs/cli.md)
   portless-studio mcp                 Run an MCP server on stdio so AI agents can list, name and
                                       stop dev servers through the running Studio (docs/mcp.md)
   portless-studio run [--name <name>] [--cwd <dir>] -- <command...>
@@ -32,7 +36,10 @@ Options:
   --no-open        Do not open the browser
   --no-register    Do not register the "studio" portless alias for the dashboard
   -y, --yes        With init and uninstall: accept every default without asking
-  --json           With doctor, config and list: print JSON for scripts and agents
+  --json           With doctor, config, list and env: print JSON for scripts and agents
+  --prefix <p>     With env: put p in front of every key, e.g. VITE_ or NEXT_PUBLIC_
+  --strip <s>      With env: drop the .s suffix from names before they become keys
+  --direct         With env: use http://localhost:<port> instead of the named URL
   --name <name>    With run: name for the port the command opens (default: the suggested one)
   --cwd <dir>      With run: folder to run in (default: the current folder)
   -h, --help       Show this help
@@ -52,6 +59,7 @@ const SUBCOMMANDS = new Set([
     "config",
     "doctor",
     "list",
+    "env",
     "mcp",
     "run",
     "open",
@@ -91,6 +99,16 @@ export function parseCliArgs(argv) {
         return ok({ command: "doctor", json });
     if (subcommand === "list")
         return ok({ command: "list", json });
+    if (subcommand === "env") {
+        return ok({
+            command: "env",
+            json,
+            direct: values.direct === true,
+            prefix: values.prefix?.trim() || null,
+            strip: values.strip?.trim() || null,
+            names: positionals.map((name) => name.trim()).filter((name) => name !== ""),
+        });
+    }
     if (subcommand === "mcp")
         return ok({ command: "mcp" });
     if (subcommand === "run") {
@@ -152,23 +170,34 @@ function parseFlags(args, subcommand) {
             ? { ...common, edit: { type: "boolean" }, json }
             : subcommand === "doctor" || subcommand === "list"
                 ? { ...common, json }
-                : subcommand === "service" || subcommand === "mcp" || subcommand === "open"
-                    ? common
-                    : subcommand === "run"
-                        ? { ...common, name: { type: "string" }, cwd: { type: "string" } }
-                        : {
-                            ...common,
-                            port: { type: "string" },
-                            open: { type: "boolean" },
-                            register: { type: "boolean" },
-                        };
+                : subcommand === "env"
+                    ? {
+                        ...common,
+                        json,
+                        direct: { type: "boolean" },
+                        prefix: { type: "string" },
+                        strip: { type: "string" },
+                    }
+                    : subcommand === "service" || subcommand === "mcp" || subcommand === "open"
+                        ? common
+                        : subcommand === "run"
+                            ? { ...common, name: { type: "string" }, cwd: { type: "string" } }
+                            : {
+                                ...common,
+                                port: { type: "string" },
+                                open: { type: "boolean" },
+                                register: { type: "boolean" },
+                            };
     // parseArgs learned `allowNegative` in Node 22.4; reading `--no-<flag>` here keeps every Node 22.
     const { args: positive, negated } = splitNegations(args, options);
     const { values, positionals, tokens } = parseArgs({
         args: positive,
         options,
         tokens: true,
-        allowPositionals: subcommand === "service" || subcommand === "run" || subcommand === "open",
+        allowPositionals: subcommand === "service" ||
+            subcommand === "run" ||
+            subcommand === "open" ||
+            subcommand === "env",
     });
     for (const token of tokens) {
         if (token.kind === "option" && options[token.name]?.type === "boolean") {

package/dist/cli/env-command.js

@@ -0,0 +1,34 @@
+import { envEntries, formatEnvLine, selectEnvRoutes, } from "../core/routes/env-lines.js";
+/** `portless-studio env`: `KEY=url` lines for a `.env` file, one per named route. */
+export async function runEnvCommand(options) {
+    const fromStudio = await options.readFromStudio();
+    const routes = fromStudio.ok ? fromStudio.value : await options.readLocally();
+    const selected = selectEnvRoutes(routes, options.names);
+    if (!selected.ok)
+        return fail(options, selected.error);
+    const entries = envEntries(selected.value, {
+        direct: options.direct,
+        ...(options.prefix === null ? {} : { prefix: options.prefix }),
+        ...(options.strip === null ? {} : { strip: options.strip }),
+    });
+    if (!entries.ok)
+        return fail(options, entries.error);
+    if (options.json) {
+        const source = fromStudio.ok ? "studio" : "local";
+        options.print(JSON.stringify({ source, variables: entries.value }, null, 2));
+        return 0;
+    }
+    if (!fromStudio.ok) {
+        options.printError("(Studio is not running: read directly from portless.)");
+    }
+    if (entries.value.length === 0) {
+        options.printError("No named routes yet.");
+        return 0;
+    }
+    options.print(entries.value.map(formatEnvLine).join("\n"));
+    return 0;
+}
+function fail(options, message) {
+    options.printError(`Error: ${message}`);
+    return 1;
+}

package/dist/cli/index.js

@@ -11,6 +11,7 @@ import { HELP, parseCliArgs, resolveStartSettings, } from "./cli-args.js";
 import { runCommand } from "./command-runner.js";
 import { editConfig, printConfig, printConfigJson } from "./config-command.js";
 import { runDoctorCommand } from "./doctor-command.js";
+import { runEnvCommand } from "./env-command.js";
 import { runOpenCommand } from "./focus-command.js";
 import { runInit } from "./init.js";
 import { runListCommand } from "./list-command.js";
@@ -65,6 +66,9 @@ async function main() {
         case "list":
             await list(options.json);
             return;
+        case "env":
+            await env(options);
+            return;
         case "mcp":
             await mcp();
             return;
@@ -125,6 +129,21 @@ async function list(json) {
     // The local fallback may leave scan timers behind; the list is all this command does.
     process.exit(code);
 }
+async function env(options) {
+    const client = await studioClient();
+    const code = await runEnvCommand({
+        ...options,
+        print,
+        printError: (line) => console.error(line),
+        readFromStudio: async () => {
+            const snapshot = await client.read(API_PATHS.snapshot);
+            return snapshot.ok ? { ok: true, value: snapshot.value.routes } : snapshot;
+        },
+        readLocally: async () => (await createStudioServices().registry.readSnapshot()).routes,
+    });
+    // The local fallback may leave watchers behind; the lines are all this command prints.
+    process.exit(code);
+}
 /** stdout carries only protocol messages; warnings go to stderr through `console.error`. */
 async function mcp() {
     const client = await studioClient();

package/dist/cli/mcp/studio-tools.js

@@ -1,5 +1,6 @@
-import { API_PATHS, } from "../../core/api/contract.js";
+import { API_PATHS, INCLUDE_STUDIO_PARAM, } from "../../core/api/contract.js";
 import { err, ok } from "../../core/result.js";
+import { envEntries, formatEnvLine, selectEnvRoutes } from "../../core/routes/env-lines.js";
 import { plainText } from "../../core/terminals/terminal.js";
 import { describeProxy, detectedItem, proxyItem, routeItem } from "../studio-items.js";
 const NAMING_HINT = "Make each name say what the work is: start it with the ticket key, PR number or a short task " +
@@ -15,6 +16,7 @@ export const AGENT_INSTRUCTIONS = [
     "Start dev servers with run_in_terminal (or `portless-studio run -- <command>` in a shell) instead",
     "of in your own shell, so the user can watch their output in Studio; read it with read_terminal.",
     "When the user asks to see something, call focus_studio.",
+    "To point an app at another one by name in a .env file, call env_lines and write its lines.",
     NAMING_HINT,
 ].join(" ");
 const PROXY_ACTIONS = ["start", "stop", "restart"];
@@ -37,10 +39,20 @@ export function createStudioTools(client) {
             title: "List named routes",
             description: "Lists every portless route Studio knows: name, browser URL, local port, kind (app or alias), " +
                 "health (up, error, down), project and git worktree it runs from, and pid. Use it to find the " +
-                "URL of a running app or which ports a worktree uses.",
-            inputSchema: NO_INPUT,
-            call: async () => {
-                const snapshot = await readSnapshot(client);
+                "URL of a running app or which ports a worktree uses. Studio's own route is left out unless " +
+                "include_studio is true.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    include_studio: {
+                        type: "boolean",
+                        description: "Also list Studio's own route (studio), hidden by default.",
+                    },
+                },
+                additionalProperties: false,
+            },
+            call: async (args) => {
+                const snapshot = await readSnapshot(client, args.include_studio === true);
                 if (!snapshot.ok)
                     return snapshot.error;
                 const { routes, proxy } = snapshot.value;
@@ -51,6 +63,54 @@ export function createStudioTools(client) {
                 };
             },
         },
+        {
+            name: "env_lines",
+            title: "Build .env lines from route names",
+            description: "Returns KEY=url lines for a .env file, one per route: api.acme becomes " +
+                "API_ACME_URL=http://api.acme.localhost:1355, a URL that keeps working when the port " +
+                "changes. names keeps only those routes (acme also keeps every *.acme route); prefix puts " +
+                "VITE_ or NEXT_PUBLIC_ in front; strip drops a suffix like the project (acme turns api.acme " +
+                "into API_URL); direct uses http://localhost:<port> instead. It only returns text: write " +
+                "the lines into the user's .env.local yourself when they ask.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    names: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: 'Route names to keep, e.g. ["acme"]; all routes when absent',
+                    },
+                    prefix: { type: "string", description: "Put in front of every key, e.g. VITE_" },
+                    strip: { type: "string", description: "Suffix dropped from names, e.g. acme" },
+                    direct: { type: "boolean", description: "Use http://localhost:<port> (default false)" },
+                },
+                additionalProperties: false,
+            },
+            call: async (args) => {
+                const names = Array.isArray(args.names)
+                    ? args.names.filter((name) => typeof name === "string" && name !== "")
+                    : [];
+                const snapshot = await readSnapshot(client);
+                if (!snapshot.ok)
+                    return snapshot.error;
+                const selected = selectEnvRoutes(snapshot.value.routes, names);
+                if (!selected.ok)
+                    return { summary: selected.error, isError: true };
+                const entries = envEntries(selected.value, {
+                    direct: args.direct === true,
+                    ...(typeof args.prefix === "string" ? { prefix: args.prefix.trim() } : {}),
+                    ...(typeof args.strip === "string" ? { strip: args.strip } : {}),
+                });
+                if (!entries.ok)
+                    return { summary: entries.error, isError: true };
+                if (entries.value.length === 0)
+                    return { summary: "No named routes yet.", data: { variables: [] } };
+                return {
+                    summary: entries.value.map(formatEnvLine).join("\n"),
+                    data: { variables: entries.value },
+                };
+            },
+        },
         {
             name: "list_detected_ports",
             title: "List ports without a name",
@@ -553,8 +613,11 @@ function terminalItem(terminal) {
         port: terminal.naming?.port ?? null,
     };
 }
-async function readSnapshot(client) {
-    const result = await client.read(API_PATHS.snapshot);
+async function readSnapshot(client, includeStudio = false) {
+    const path = includeStudio
+        ? `${API_PATHS.snapshot}?${INCLUDE_STUDIO_PARAM}=1`
+        : API_PATHS.snapshot;
+    const result = await client.read(path);
     if (!result.ok)
         return err(failure(result.error));
     return ok(result.value);

package/dist/cli/studio-items.js

@@ -22,10 +22,13 @@ export function detectedItem(port) {
     };
 }
 export function proxyItem(proxy) {
-    return { running: proxy.running, port: proxy.port };
+    const item = { running: proxy.running, port: proxy.port };
+    return proxy.publicPort == null ? item : { ...item, publicPort: proxy.publicPort };
 }
+/** `publicPort` is set while Studio forwards it to the proxy, for URLs without a port. */
 export function describeProxy(proxy) {
     if (!proxy.running)
         return "proxy stopped";
-    return proxy.port === null ? "proxy running" : `proxy running on port ${proxy.port}`;
+    const running = proxy.port === null ? "proxy running" : `proxy running on port ${proxy.port}`;
+    return proxy.publicPort == null ? running : `${running}, names open on port ${proxy.publicPort}`;
 }