chore(cli): require explicit target for attach

- attach now errors if no positional target / --cdp / --extension is
  supplied; the implicit fallback through PLAYWRIGHT_CLI_SESSION /
  --config is gone.
- list output drops the per-server status line; serverRegistry.list()
  already filters to connectable descriptors, so dashboard and
  sessionSidebar drop their redundant canConnect filters too.
- Attach helper text suggests the short --s= form.

Author: pavelfeldman

packages/dashboard/src/dashboardChannel.ts

@@ -15,9 +15,9 @@
  */
 
 import type { ClientInfo } from '../../playwright-core/src/tools/cli-client/registry';
-import type { BrowserStatus } from '../../playwright-core/src/serverRegistry';
+import type { BrowserDescriptor } from '../../playwright-core/src/serverRegistry';
 
-export type SessionStatus = BrowserStatus;
+export type SessionStatus = BrowserDescriptor;
 
 export type Tab = {
   browser: string;

packages/dashboard/src/sessionSidebar.tsx

@@ -78,7 +78,7 @@ const TabRow: React.FC<{ tab: Tab; model: DashboardModel }> = ({ tab, model }) =
 
 export const SessionSidebar: React.FC<SessionSidebarProps> = ({ model }) => {
   const { sessions, clientInfo, loadingSessions, tabs: allTabs } = model.state;
-  const openSessions = React.useMemo(() => sessions.filter(session => session.canConnect), [sessions]);
+  const openSessions = sessions;
 
   const tabsByBrowserAndContext = React.useMemo(() => {
     const map = new Map<string, Map<string, Tab[]>>();

packages/playwright-core/src/serverRegistry.ts

@@ -89,7 +89,7 @@ class ServerRegistry extends EventEmitter {
     return this._ready ?? Promise.resolve();
   }
 
-  async list(): Promise<Map<string, BrowserStatus[]>> {
+  async list(): Promise<Map<string, BrowserDescriptor[]>> {
     const ownWatcher = !this._watcher;
     let dispose: (() => void) | undefined;
     if (ownWatcher)
@@ -102,7 +102,7 @@ class ServerRegistry extends EventEmitter {
             return { descriptor, canConnect };
           }),
       );
-      const result = new Map<string, BrowserStatus[]>();
+      const result = new Map<string, BrowserDescriptor[]>();
       for (const { descriptor, canConnect } of statuses) {
         if (!canConnect) {
           await fs.promises.unlink(path.join(this._browsersDir(), descriptor.browser.guid)).catch(() => {});
@@ -114,7 +114,7 @@ class ServerRegistry extends EventEmitter {
           list = [];
           result.set(key, list);
         }
-        list.push({ ...descriptor, canConnect });
+        list.push(descriptor);
       }
       return result;
     } finally {
@@ -133,7 +133,7 @@ class ServerRegistry extends EventEmitter {
       endpoint: endpoint.endpoint,
       workspaceDir: endpoint.workspaceDir,
     };
-    await fs.promises.writeFile(file, JSON.stringify(descriptor), 'utf-8');
+    await fs.promises.writeFile(file, JSON.stringify(descriptor, null, 2), 'utf-8');
   }
 
   async delete(guid: string): Promise<void> {

packages/playwright-core/src/tools/cli-client/output.ts

@@ -22,7 +22,7 @@ import path from 'path';
 import { playwrightExtensionInstallUrl } from '../utils/extension';
 
 import type { ChannelSession } from './channelSessions';
-import type { BrowserStatus } from '../../serverRegistry';
+import type { BrowserDescriptor } from '../../serverRegistry';
 
 export type ListedBrowser = {
   name: string;
@@ -40,7 +40,7 @@ export type ListedBrowser = {
 export type ListData = {
   all: boolean;
   browsers: ListedBrowser[];
-  servers?: BrowserStatus[];
+  servers?: BrowserDescriptor[];
   channelSessions?: ChannelSession[];
 };
 
@@ -55,6 +55,7 @@ export interface Output {
   errorAttachConflict(): never;
   errorDetachNotAttached(session: string): never;
   errorBrowserNotOpenForTool(session: string): never;
+  errorAttachNoTarget(): never;
 
   list(data: ListData): void;
   closeAll(sessions: string[]): void;
@@ -112,6 +113,11 @@ export class TextOutput implements Output {
     return process.exit(1);
   }
 
+  errorAttachNoTarget(): never {
+    console.error(`Error: no target specified for attach command; use one of [name], --cdp, --endpoint, or --extension to specify the target to attach to.`);
+    return process.exit(1);
+  }
+
   list({ all, browsers, servers, channelSessions }: ListData): void {
     const byWorkspace = new Map<string, ListedBrowser[]>();
     for (const browser of browsers) {
@@ -144,7 +150,7 @@ export class TextOutput implements Output {
       if (count)
         console.log('');
       console.log('### Browser servers available for attach');
-      const serversByWorkspace = new Map<string, BrowserStatus[]>();
+      const serversByWorkspace = new Map<string, BrowserDescriptor[]>();
       for (const server of servers) {
         let list = serversByWorkspace.get(server.workspaceDir ?? '');
         if (!list) {
@@ -204,7 +210,8 @@ export class TextOutput implements Output {
   attach(session: string, pid: number | undefined, endpoint: string | undefined, toolResult: string): void {
     if (endpoint) {
       console.log(`### Session \`${session}\` created, attached to \`${endpoint}\`.`);
-      console.log(`Run commands with: playwright-cli --session=${session} <command>`);
+      console.log(`Run commands with: playwright-cli --s=${session} <command>`);
+      console.log('');
     } else {
       console.log(`### Browser \`${session}\` opened with pid ${pid}.`);
     }
@@ -282,6 +289,11 @@ export class JsonOutput implements Output {
     return process.exit(1);
   }
 
+  errorAttachNoTarget(): never {
+    this._emit({ isError: true, error: `no target specified for attach command; use one of [name], --cdp, --endpoint, or --extension to specify the target to attach to.` });
+    return process.exit(1);
+  }
+
   list({ all, browsers, servers, channelSessions }: ListData): void {
     const payload: Record<string, unknown> = { browsers };
     if (all) {
@@ -372,11 +384,10 @@ function renderBrowser(browser: ListedBrowser): string {
   return lines.join('\n');
 }
 
-function renderServer(server: BrowserStatus): string {
+function renderServer(server: BrowserDescriptor): string {
   const lines = [`- browser "${server.title}":`];
   lines.push(`  - browser: ${server.browser.browserName}`);
   lines.push(`  - version: v${server.playwrightVersion}`);
-  lines.push(`  - status: ${server.canConnect ? 'open' : 'closed'}`);
   if (server.browser.userDataDir)
     lines.push(`  - data-dir: ${server.browser.userDataDir}`);
   else

packages/playwright-core/src/tools/cli-client/program.ts

@@ -165,13 +165,17 @@ export async function program(options?: { embedderVersion?: string}) {
         args.browser = args.extension;
         args.extension = true;
       }
+
       const cdpChannel = typeof args.cdp === 'string' && isKnownChannel(args.cdp) ? args.cdp : undefined;
+      const targetName = attachTarget ?? cdpChannel ?? extensionChannel ?? args.cdp as string;
+      if (!targetName)
+        output.errorAttachNoTarget();
       const attachSessionName = explicitSessionName(args.session as string) ?? attachTarget ?? cdpChannel ?? extensionChannel ?? sessionName;
       args.session = attachSessionName;
-      const { pid, endpoint } = await startSession(attachSessionName, registry, clientInfo, args, 'attach');
+      const { pid } = await startSession(attachSessionName, registry, clientInfo, args, 'attach');
       const newEntry = await registry.loadEntry(clientInfo, attachSessionName);
       const toolText = await runInSession(newEntry, clientInfo, { _: ['snapshot'], filename: '<auto>' }, output);
-      output.attach(attachSessionName, pid, endpoint, toolText);
+      output.attach(attachSessionName, pid, targetName, toolText);
       return;
     }
     case 'close': {
@@ -341,14 +345,17 @@ async function killAllDaemons(): Promise<number[]> {
 async function collectList(registry: Registry, clientInfo: ClientInfo, all: boolean): Promise<ListData> {
   const browsers: ListedBrowser[] = [];
   const entries = registry.entryMap();
+
+  // List early to GC.
+  const serverEntries = await serverRegistry.list();
   const key = clientKey(clientInfo);
   for (const [workspaceKey, list] of entries) {
     if (!all && workspaceKey !== key)
       continue;
     for (const entry of list) {
       const session = new Session(entry);
       const canConnect = await session.canConnect();
-      if (!canConnect && !session.config.cli.persistent) {
+      if (!canConnect) {
         await session.deleteSessionConfig();
         continue;
       }
@@ -372,7 +379,6 @@ async function collectList(registry: Registry, clientInfo: ClientInfo, all: bool
   if (!all)
     return { all, browsers };
 
-  const serverEntries = await serverRegistry.list();
   const servers = [...serverEntries.values()].flat();
   return { all, browsers, servers, channelSessions: await listChannelSessions() };
 }

packages/playwright-core/src/tools/cli-client/skill/SKILL.md

@@ -209,8 +209,8 @@ playwright-cli open --persistent
 # Use persistent profile with custom directory
 playwright-cli open --profile=/path/to/profile
 
-# Connect to browser via extension
-playwright-cli attach --extension
+# Connect to browser via Playwright Extension
+playwright-cli attach --extension=chrome
 
 # Connect to a running Chrome or Edge by channel name
 playwright-cli attach --cdp=chrome

packages/playwright-core/src/tools/dashboard/dashboardController.ts

@@ -28,7 +28,7 @@ import { createClientInfo } from '../cli-client/registry';
 import type * as api from '../../..';
 import type { Transport } from '@utils/httpServer';
 import type { AnnotationData, Tab } from '@dashboard/dashboardChannel';
-import type { BrowserDescriptor, BrowserStatus } from '../../serverRegistry';
+import type { BrowserDescriptor } from '../../serverRegistry';
 
 type BrowserTrackerCallbacks = {
   onTabsChanged: () => void;
@@ -274,7 +274,7 @@ export class DashboardConnection implements Transport {
     return this._visible;
   }
 
-  emitSessions(sessions: BrowserStatus[]) {
+  emitSessions(sessions: BrowserDescriptor[]) {
     this.sendEvent?.('sessions', { sessions, clientInfo: createClientInfo() });
   }
 
@@ -379,7 +379,7 @@ export class DashboardConnection implements Transport {
       this._pushSessionsScheduled = false;
       try {
         const byWs = await serverRegistry.list();
-        const sessions: BrowserStatus[] = [];
+        const sessions: BrowserDescriptor[] = [];
         for (const list of byWs.values()) {
           for (const status of list) {
             if (status.title.startsWith('--playwright-internal'))
@@ -397,12 +397,10 @@ export class DashboardConnection implements Transport {
     });
   };
 
-  private async _reconcile(sessions: BrowserStatus[]) {
-    const connectable = new Map<string, BrowserStatus>();
-    for (const status of sessions) {
-      if (status.canConnect)
-        connectable.set(status.browser.guid, status);
-    }
+  private async _reconcile(sessions: BrowserDescriptor[]) {
+    const connectable = new Map<string, BrowserDescriptor>();
+    for (const status of sessions)
+      connectable.set(status.browser.guid, status);
 
     for (const [guid, slot] of this._browsers) {
       if (connectable.has(guid))

tests/mcp/cli-cdp.spec.ts

@@ -93,10 +93,9 @@ test('cdp server', async ({ cdpServer, cli, server }) => {
 
   const configPath = test.info().outputPath('config.ini');
   await fs.promises.writeFile(configPath, `
-browser.cdpEndpoint=${cdpServer.endpoint}
 browser.isolated=false
 `);
-  await cli('attach', `--config=${configPath}`);
+  await cli('attach', `--cdp=${cdpServer.endpoint}`, `--config=${configPath}`);
   const { inlineSnapshot } = await cli('snapshot');
   expect(inlineSnapshot).toContain(`- generic [active] [ref=e1]: Hello, world!`);
 });

tests/mcp/cli-session.spec.ts

@@ -69,19 +69,6 @@ test('close non-running session', async ({ cli }) => {
   expect(output).toContain(`Browser 'nonexistent' is not open.`);
 });
 
-test('persistent session shows in list after close', async ({ cli, server }) => {
-  await cli('open', server.HELLO_WORLD, '--persistent');
-
-  const { output: listBefore } = await cli('list');
-  expect(listBefore).toContain('- default:');
-  expect(listBefore).not.toContain('<in-memory>');
-
-  await cli('close');
-
-  const { output: listAfter } = await cli('list');
-  expect(listAfter).toContain('- default:');
-});
-
 test('close-all', async ({ cli, server }) => {
   await cli('-s', 'session1', 'open', server.HELLO_WORLD);
   await cli('-s', 'session2', 'open', server.HELLO_WORLD);
@@ -310,7 +297,6 @@ workspace1:
 - browser "foobar":
   - browser: ${/* FIX browser._options */ mcpBrowser.replace('chrome', 'chromium')}
   - version: ${version}
-  - status: open
   - data-dir: <in-memory>
   - run \`playwright-cli attach "foobar"\` to attach`);
   });
@@ -323,7 +309,7 @@ workspace1:
     await page.setContent('<title>My Page</title>');
     const { output: openOutput } = await cli('attach', 'foobar');
     expect(openOutput).toContain('### Session `foobar` created, attached to `foobar`.');
-    expect(openOutput).toContain('Run commands with: playwright-cli --session=foobar <command>');
+    expect(openOutput).toContain('Run commands with: playwright-cli --s=foobar <command>');
     const { output: listOutput } = await cli('list', '--all');
     expect(listOutput).toBe(`### Browsers
 /:
@@ -336,7 +322,6 @@ workspace1:
 - browser "foobar":
   - browser: ${mcpBrowser.replace('chrome', 'chromium')}
   - version: ${version}
-  - status: open
   - data-dir: <in-memory>
   - run \`playwright-cli attach "foobar"\` to attach`);
   });
@@ -349,33 +334,6 @@ workspace1:
     expect(error).toContain('Error: unable to connect to a browser that does not have any contexts');
   });
 
-  test('attach via PLAYWRIGHT_CLI_SESSION env', async ({ cli, mcpBrowser }) => {
-    const browserName = mcpBrowser.replace('chrome', 'chromium');
-    await using browser = await playwright[browserName].launch({ headless: true });
-    const page = await browser.newPage();
-    await page.setContent('<title>Env Page</title><h1>Hello from env</h1>');
-    await browser.bind('foobar', { workspaceDir: 'workspace1' });
-    const { output: openOutput, snapshot } = await cli('attach', { env: { PLAYWRIGHT_CLI_SESSION: 'foobar' } });
-    expect(openOutput).toContain('### Browser `foobar` opened with pid');
-    expect(openOutput).toContain('Env Page');
-    expect(snapshot).toContain('Hello from env');
-    const { output: listOutput } = await cli('list', '--all');
-    expect(listOutput).toBe(`### Browsers
-/:
-- foobar:
-  - status: open
-  - browser-type: ${mcpBrowser.replace('chrome', 'chromium')} (attached)
-
-### Browser servers available for attach
-workspace1:
-- browser "foobar":
-  - browser: ${mcpBrowser.replace('chrome', 'chromium')}
-  - version: ${version}
-  - status: open
-  - data-dir: <in-memory>
-  - run \`playwright-cli attach "foobar"\` to attach`);
-  });
-
   test('attach with session alias', async ({ cli, mcpBrowser }) => {
     const browserName = mcpBrowser.replace('chrome', 'chromium');
     await using browser = await playwright[browserName].launch({ headless: true });
@@ -384,7 +342,7 @@ workspace1:
     await page.setContent('<title>Alias Page</title>');
     const { output: openOutput } = await cli('attach', 'foobar', '--session=mybrowser');
     expect(openOutput).toContain('### Session `mybrowser` created, attached to `foobar`.');
-    expect(openOutput).toContain('Run commands with: playwright-cli --session=mybrowser <command>');
+    expect(openOutput).toContain('Run commands with: playwright-cli --s=mybrowser <command>');
     await cli('-s', 'mybrowser', 'close');
   });
 
@@ -402,7 +360,6 @@ workspace1:
 - browser \"foobar\":
   - browser: ${/* FIX browser._options */ mcpBrowser.replace('chrome', 'chromium')}
   - version: ${version}
-  - status: open
   - data-dir: <in-memory>
   - run \`playwright-cli attach \"foobar\"\` to attach`);
   });