playwriter 0.3.0 → 0.4.0

package/src/cli.ts

@@ -4,7 +4,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import util from 'node:util'
 import { fileURLToPath } from 'node:url'
-import { goke } from 'goke'
+import { goke, openInBrowser } from 'goke'
 import { z } from 'zod'
 import pc from 'picocolors'
 
@@ -24,11 +24,10 @@ import {
   type ExtensionStatus,
 } from './relay-client.js'
 import { discoverChromeInstances, resolveDirectInput, type DiscoveredInstance } from './chrome-discovery.js'
+import { getCloudClient, loadCloudAuth, saveCloudAuth, CloudClient, buildLiveUrl } from './cloud-client.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
-const cliRelayEnv = { PLAYWRITER_AUTO_ENABLE: '1' }
-
 const cli = goke('playwriter')
 
 cli
@@ -53,7 +52,7 @@ cli
           import('./package-paths.js'),
         ])
 
-        await ensureRelayServer({ logger: console, env: cliRelayEnv })
+        await ensureRelayServer({ logger: console })
 
         const browserPath = resolveBrowserExecutablePath({ browserPath: binaryPath })
         const extensionPath = getBundledExtensionPath()
@@ -99,6 +98,18 @@ cli
     },
   )
 
+cli
+  .command('browser install', 'Download Chrome for Testing for headless browser automation')
+  .action(async () => {
+    try {
+      const { installChrome } = await import('./browser-install.js')
+      await installChrome()
+    } catch (error: any) {
+      console.error(`Error: ${error.message}`)
+      process.exit(1)
+    }
+  })
+
 cli
   .command('', 'Start the MCP server or controls the browser with -e')
   .option('--host <host>', 'Remote relay server host to connect to (or use PLAYWRITER_HOST env var)')
@@ -106,8 +117,13 @@ cli
   .option('-s, --session <name>', 'Session ID (required for -e, get one with `playwriter session new`)')
   .option('-e, --eval <code>', 'Execute JavaScript code and exit, read https://playwriter.dev/SKILL.md for usage')
   .option('-f, --file <path>', 'Execute JavaScript from a file and exit')
+  .option('--patchright', 'Use @playwriter/patchright-core for stealth mode (bypasses bot detection)')
   .option('--timeout [ms]', z.number().default(10000).describe('Execution timeout in milliseconds'))
   .action(async (options) => {
+    if (options.patchright) {
+      process.env.PLAYWRITER_PATCHRIGHT = '1'
+    }
+
     if (options.eval && options.file) {
       console.error('Error: -e and -f cannot be used together.')
       process.exit(1)
@@ -237,7 +253,7 @@ async function executeCode(options: {
 
   // Ensure relay server is running (only for local)
   if (!host && !process.env.PLAYWRITER_HOST) {
-    const restarted = await ensureRelayServer({ logger: console, env: cliRelayEnv })
+    const restarted = await ensureRelayServer({ logger: console })
     if (restarted) {
       const connectedExtensions = await waitForConnectedExtensions({
         logger: console,
@@ -278,6 +294,7 @@ async function executeCode(options: {
       images: Array<{ data: string; mimeType: string }>
       screenshots: Array<{ path: string; base64: string; snapshot: string; labelCount: number }>
       isError: boolean
+      isCloud?: boolean
     }
 
     // Print output
@@ -321,6 +338,10 @@ async function executeCode(options: {
       }
     }
 
+    if (result.isCloud) {
+      console.error(pc.dim(`\nCloud session. Run \`playwriter session delete ${sessionId}\` when done.`))
+    }
+
     if (result.isError) {
       process.exit(1)
     }
@@ -340,7 +361,7 @@ async function executeCode(options: {
 // Unified browser option type used in the multi-browser selection table
 interface BrowserOption {
   key: string
-  type: 'extension' | 'direct'
+  type: 'extension' | 'direct' | 'cloud' | 'headless'
   browser: string
   profile: string
   /** For extension entries */
@@ -349,16 +370,68 @@ interface BrowserOption {
   wsUrl?: string
   /** Raw profile data from discovery (for passing to relay) */
   profiles?: Array<{ name: string; email: string }>
+  /** For cloud entries — active BU session's cloud session ID (if VM is running) */
+  activeCloudSessionId?: string
 }
 
 cli
   .command('session new', 'Create a new session and print the session ID')
   .option('--host <host>', 'Remote relay server host')
   .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
-  .option('--browser <key>', 'Browser key when multiple browsers are available')
+  .option('--browser <key>', 'Browser key when multiple browsers are available. Special values: "headless" (launch headless Chrome, no extension), "cloud" (cloud browser with stealth/proxies)')
+  .option('--patchright', 'Use @playwriter/patchright-core for stealth mode (bypasses bot detection)')
   .option('--direct [endpoint]', 'Use direct CDP connection without the extension. Enable debugging first at chrome://inspect/#remote-debugging or launch Chrome with --remote-debugging-port=9222. Auto-discovers instances or accepts an explicit ws:// endpoint')
+  .option('--proxy <region>', 'Enable residential proxy for cloud browser (e.g. us, de, jp). Disabled by default. Use for anti-detection or geo-targeting.')
+  .option('--custom-proxy <url>', 'Custom proxy for cloud browser (host:port or user:pass@host:port)')
+  .option('--timeout <minutes>', 'Cloud browser timeout in minutes (1-240, default 60)')
+  .option('--disable-proxy-bandwidth-acceleration', 'Allow loading images, video, and fonts when proxy is enabled (they are blocked by default to save proxy bandwidth)')
   .action(async (options) => {
+    if (options.patchright) {
+      process.env.PLAYWRITER_PATCHRIGHT = '1'
+    }
+
     const isLocal = !options.host && !process.env.PLAYWRITER_HOST
+
+    // --browser headless: launch headless Chrome via chromium.launch(), no extension
+    if (options.browser === 'headless') {
+      try {
+        await ensureRelayForSessionCreation(isLocal)
+        const serverUrl = await getServerUrl(options.host)
+        const response = await fetch(`${serverUrl}/cli/session/new`, {
+          method: 'POST',
+          headers: buildAuthHeaders({ token: options.token, json: true }),
+          body: JSON.stringify({ headless: true, cwd: process.cwd() }),
+        })
+        if (!response.ok) {
+          const text = await response.text()
+          if (text.includes('Could not find a supported browser binary')) {
+            console.error('No Chrome browser found. Install one first:')
+            console.error('')
+            console.error('  playwriter browser install')
+            console.error('')
+            console.error('This downloads Chrome for Testing from Google.')
+            process.exit(1)
+          }
+          console.error(`Error: ${response.status} ${text}`)
+          process.exit(1)
+        }
+        const result = (await response.json()) as { id: string }
+        console.log(`Session ${result.id} created (headless). Use with: playwriter -s ${result.id} -e "..."`)
+        console.log(pc.dim('NOTE: Recording unavailable in headless mode.'))
+      } catch (error: any) {
+        if (error.message?.includes('Could not find a supported browser binary')) {
+          console.error('No Chrome browser found. Install one first:')
+          console.error('')
+          console.error('  playwriter browser install')
+          console.error('')
+          console.error('This downloads Chrome for Testing from Google.')
+          process.exit(1)
+        }
+        console.error(`Error: ${error.message}`)
+        process.exit(1)
+      }
+      return
+    }
     // goke 6.6: optional-value flags are string | undefined
     //   `--direct ws://...` → 'ws://...' (explicit endpoint)
     //   `--direct`          → ''          (bare flag, auto-discover)
@@ -425,6 +498,7 @@ cli
           return opt.key === options.browser
         })
         if (!selected) {
+          await handleCloudBrowserNotFound(options.browser, { hasCloudOptions: false })
           console.error(`Browser not found: ${options.browser}`)
           console.error('Available: ' + directOptions.map((opt) => opt.key).join(', '))
           process.exit(1)
@@ -445,7 +519,7 @@ cli
     let extensions: ExtensionStatus[] = []
 
     if (isLocal) {
-      await ensureRelayServer({ logger: console, env: cliRelayEnv })
+      await ensureRelayServer({ logger: console })
       extensions = await waitForConnectedExtensions({
         timeoutMs: 12000,
         pollIntervalMs: 250,
@@ -465,8 +539,57 @@ cli
     }
 
     if (extensions.length === 0) {
+      // Before giving up, check if cloud browsers are available
+      const cloudOptions = await discoverCloudBrowsers()
+      if (cloudOptions.length > 0) {
+        // Cloud-only user: skip extension requirement, show cloud options
+        await ensureRelayForSessionCreation(isLocal)
+        const allOptions: BrowserOption[] = [...cloudOptions]
+
+        if (options.browser) {
+          const selected = allOptions.find((opt) => { return opt.key === options.browser })
+          if (!selected) {
+            await handleCloudBrowserNotFound(options.browser, { hasCloudOptions: true })
+            console.error(`Browser not found: ${options.browser}`)
+            console.error('Available: ' + allOptions.map((opt) => opt.key).join(', '))
+            process.exit(1)
+          }
+          const serverUrl = await getServerUrl(options.host)
+          // Reuse existing running VM if selected, otherwise create new
+          const result = selected.activeCloudSessionId
+            ? await attachExistingCloudSession({
+              serverUrl,
+              cloudSessionId: selected.activeCloudSessionId,
+              blockProxyResources: computeBlockProxyResources(options),
+              token: options.token,
+            })
+            : await createCloudSession({
+              serverUrl,
+              proxyRegion: options.proxy,
+              customProxy: options.customProxy,
+              timeout: parseCloudTimeout(options.timeout),
+              blockProxyResources: computeBlockProxyResources(options),
+              token: options.token,
+            })
+          console.log(`Session ${result.id} created (cloud). Use with: playwriter -s ${result.id} -e "..."`)
+          if (result.liveUrl) {
+            console.log(pc.dim(`Live view: ${result.liveUrl}`))
+          }
+          return
+        }
+
+        console.log('\nNo local browsers detected, but cloud browsers are available:\n')
+        printBrowserTable(allOptions)
+        console.log('\nRun again with --browser <key>.')
+        process.exit(1)
+      }
+
+      if (options.browser) {
+        await handleCloudBrowserNotFound(options.browser, { hasCloudOptions: false })
+      }
       console.error('No connected browsers detected. Click the Playwriter extension icon.')
       console.error(pc.dim('Tip: Use --direct to connect via Chrome DevTools Protocol instead.'))
+      console.error(pc.dim('Tip: Run `playwriter cloud login` to use cloud browsers.'))
       process.exit(1)
     }
 
@@ -492,7 +615,7 @@ cli
         const response = await fetch(`${serverUrl}/cli/session/new`, {
           method: 'POST',
           headers: buildAuthHeaders({ token: options.token, json: true }),
-          body: JSON.stringify({ extensionId, cwd, autoEnable: true }),
+          body: JSON.stringify({ extensionId, cwd }),
         })
         if (!response.ok) {
           const text = await response.text()
@@ -501,6 +624,7 @@ cli
         }
         const result = (await response.json()) as { id: string; extensionId: string | null }
         console.log(`Session ${result.id} created. Use with: playwriter -s ${result.id} -e "..."`)
+        printCloudTip()
       } catch (error: any) {
         console.error(`Error: ${error.message}`)
         process.exit(1)
@@ -508,13 +632,16 @@ cli
       return
     }
 
-    // Multiple extensions: also discover direct CDP instances and show unified table.
-    // Only discover locally — remote relay can't reach local Chrome debug ports.
+    // Multiple extensions: also discover direct CDP instances and cloud browsers.
+    // Direct discovery only works locally — remote relay can't reach local Chrome debug ports.
     const directInstances = isLocal ? await (async () => {
       console.log(pc.dim('Discovering additional Chrome instances...'))
       return await discoverChromeInstances()
     })() : []
 
+    // Fetch cloud browser slots if user is logged in
+    const cloudOptions = await discoverCloudBrowsers()
+
     const allOptions: BrowserOption[] = [
       ...extensions.map((ext) => {
         return {
@@ -528,6 +655,7 @@ cli
       ...directInstances.map((instance) => {
         return instanceToBrowserOption(instance)
       }),
+      ...cloudOptions,
     ]
 
     if (options.browser) {
@@ -535,6 +663,7 @@ cli
         return opt.key === options.browser
       })
       if (!selected) {
+        await handleCloudBrowserNotFound(options.browser, { hasCloudOptions: cloudOptions.length > 0 })
         console.error(`Browser not found: ${options.browser}`)
         console.error('Available: ' + allOptions.map((opt) => opt.key).join(', '))
         process.exit(1)
@@ -542,7 +671,28 @@ cli
 
       try {
         const serverUrl = await getServerUrl(options.host)
-        if (selected.type === 'direct') {
+        if (selected.type === 'cloud') {
+          // Reuse existing running VM if selected, otherwise create new
+          const result = selected.activeCloudSessionId
+            ? await attachExistingCloudSession({
+              serverUrl,
+              cloudSessionId: selected.activeCloudSessionId,
+              blockProxyResources: computeBlockProxyResources(options),
+              token: options.token,
+            })
+            : await createCloudSession({
+              serverUrl,
+              proxyRegion: options.proxy,
+              customProxy: options.customProxy,
+              timeout: parseCloudTimeout(options.timeout),
+              blockProxyResources: computeBlockProxyResources(options),
+              token: options.token,
+            })
+          console.log(`Session ${result.id} created (cloud). Use with: playwriter -s ${result.id} -e "..."`)
+          if (result.liveUrl) {
+            console.log(pc.dim(`Live view: ${result.liveUrl}`))
+          }
+        } else if (selected.type === 'direct') {
           const result = await createDirectSession({ serverUrl, cdpEndpoint: selected.wsUrl!, browser: selected.browser, profiles: selected.profiles, token: options.token })
           console.log(`Session ${result.id} created (direct CDP). Use with: playwriter -s ${result.id} -e "..."`)
           console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'))
@@ -551,7 +701,7 @@ cli
           const response = await fetch(`${serverUrl}/cli/session/new`, {
             method: 'POST',
             headers: buildAuthHeaders({ token: options.token, json: true }),
-            body: JSON.stringify({ extensionId: selected.extensionId, cwd, autoEnable: true }),
+            body: JSON.stringify({ extensionId: selected.extensionId, cwd }),
           })
           if (!response.ok) {
             const text = await response.text()
@@ -560,6 +710,7 @@ cli
           }
           const result = (await response.json()) as { id: string }
           console.log(`Session ${result.id} created. Use with: playwriter -s ${result.id} -e "..."`)
+          printCloudTip()
         }
       } catch (error: any) {
         console.error(`Error: ${error.message}`)
@@ -577,7 +728,7 @@ cli
 
 async function ensureRelayForSessionCreation(isLocal: boolean): Promise<void> {
   if (isLocal) {
-    await ensureRelayServer({ logger: console, env: cliRelayEnv })
+    await ensureRelayServer({ logger: console })
   }
 }
 
@@ -629,9 +780,286 @@ function formatInstanceProfiles(instance: DiscoveredInstance): string {
     .join(', ')
 }
 
+/** Discover cloud sessions from the website API, if logged in.
+ *  Also adds a "cloud-new" option to create a new cloud browser. */
+async function discoverCloudBrowsers(): Promise<BrowserOption[]> {
+  const client = getCloudClient()
+  if (!client) return []
+
+  try {
+    const { sessions } = await client.getStatus()
+    const options: BrowserOption[] = sessions.map((s) => {
+      return {
+        key: `cloud-${s.index}`,
+        type: 'cloud' as const,
+        browser: 'Chromium',
+        profile: `(running, expires ${new Date(s.timeoutAt).toLocaleTimeString()})`,
+        activeCloudSessionId: s.cloudSessionId,
+      }
+    })
+    // Always offer a "cloud-new" option to spin up a fresh VM
+    options.push({
+      key: 'cloud',
+      type: 'cloud' as const,
+      browser: 'Chromium',
+      profile: '(new cloud browser)',
+    })
+    return options
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    console.error(pc.dim(`Cloud browser discovery failed: ${msg}`))
+    return []
+  }
+}
+
+/** Compute whether to block images/video/fonts for proxy bandwidth savings.
+ *  Enabled by default when proxy or custom-proxy is set, disabled via
+ *  --disable-proxy-bandwidth-acceleration. */
+function computeBlockProxyResources(options: { proxy?: string; customProxy?: string; disableProxyBandwidthAcceleration?: boolean }): boolean | undefined {
+  const proxyEnabled = !!(options.proxy || options.customProxy)
+  if (!proxyEnabled) return undefined // no proxy, no blocking needed
+  if (options.disableProxyBandwidthAcceleration) return false
+  return true
+}
+
+/** Check if user requested a cloud browser that isn't available.
+ *  Shows helpful login/subscribe instructions instead of a generic "not found" error.
+ *  @param hasCloudOptions whether any cloud options were discovered (to distinguish
+ *         "not logged in" from "typo in cloud key") */
+async function handleCloudBrowserNotFound(browserKey: string, { hasCloudOptions }: { hasCloudOptions: boolean }): Promise<boolean> {
+  if (!browserKey.startsWith('cloud')) return false
+  // If cloud options exist, this is a typo (e.g. cloud-99) — let the
+  // generic "Browser not found" message show the available list instead.
+  if (hasCloudOptions) return false
+  const auth = loadCloudAuth()
+  if (!auth) {
+    console.error('Cloud browsers require authentication.')
+    console.error('')
+    console.error('  Option 1: Run `playwriter cloud login` (interactive browser flow)')
+    console.error('  Option 2: Set PLAYWRITER_API_KEY env var (create one at playwriter.dev/dashboard)')
+    console.error('')
+    console.error('  Then subscribe at playwriter.dev/dashboard and run `playwriter session new --browser cloud`')
+  } else {
+    // Verify token is still valid with a quick API check
+    const client = getCloudClient()
+    const tokenValid = await (async () => {
+      if (!client) return false
+      try {
+        await client.getStatus()
+        return true
+      } catch {
+        return false
+      }
+    })()
+
+    if (!tokenValid) {
+      console.error('Cloud authentication expired. Please re-authenticate.')
+      console.error('')
+      console.error('  Run `playwriter cloud login` or set PLAYWRITER_API_KEY env var.')
+    } else {
+      console.error('No cloud browser sessions available.')
+      console.error('')
+      console.error('  You are logged in, but you may need an active subscription.')
+      console.error('  Run `playwriter cloud subscribe` to manage your plan.')
+      console.error('  Then run `playwriter session new --browser cloud` to start a cloud browser.')
+    }
+  }
+  process.exit(1)
+}
+
+function printCloudTip(): void {
+  console.log('')
+  console.log(
+    pc.dim('Tip: Need stealth browsing, VPS control, or auto CAPTCHA solving? Run `playwriter cloud login` or set PLAYWRITER_API_KEY'),
+  )
+  console.log(
+    pc.dim('     to control a browser in the cloud instead of local Chrome.'),
+  )
+}
+
+/** Parse a custom proxy string (host:port or user:pass@host:port) into an object. */
+function parseCustomProxy(proxyStr: string): { host: string; port: number; username?: string; password?: string } {
+  // Format: [user:pass@]host:port
+  const atIdx = proxyStr.lastIndexOf('@')
+  let hostPort: string
+  let username: string | undefined
+  let password: string | undefined
+
+  if (atIdx !== -1) {
+    const userPass = proxyStr.slice(0, atIdx)
+    hostPort = proxyStr.slice(atIdx + 1)
+    const colonIdx = userPass.indexOf(':')
+    if (colonIdx !== -1) {
+      username = userPass.slice(0, colonIdx)
+      password = userPass.slice(colonIdx + 1)
+    } else {
+      username = userPass
+    }
+  } else {
+    hostPort = proxyStr
+  }
+
+  const lastColon = hostPort.lastIndexOf(':')
+  if (lastColon === -1) {
+    throw new Error(`Invalid proxy format: missing port in "${proxyStr}". Expected host:port or user:pass@host:port`)
+  }
+  const host = hostPort.slice(0, lastColon)
+  const port = parseInt(hostPort.slice(lastColon + 1), 10)
+  if (isNaN(port)) {
+    throw new Error(`Invalid proxy port in "${proxyStr}"`)
+  }
+
+  return { host, port, username, password }
+}
+
+/** Parse and validate the --timeout CLI option (integer 1-240). */
+function parseCloudTimeout(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined
+  if (!/^\d+$/.test(value)) {
+    throw new Error('--timeout must be an integer from 1 to 240')
+  }
+  const timeout = Number(value)
+  if (timeout < 1 || timeout > 240) {
+    throw new Error('--timeout must be between 1 and 240 minutes')
+  }
+  return timeout
+}
+
+/** Connect to a cloud browser and create a playwriter session via the relay. */
+async function createCloudSession({
+  serverUrl,
+  proxyRegion,
+  customProxy,
+  timeout,
+  blockProxyResources,
+  token,
+}: {
+  serverUrl: string
+  proxyRegion?: string
+  customProxy?: string
+  /** Cloud browser timeout in minutes (1-240, default 60) */
+  timeout?: number
+  /** Block images/video/fonts to save proxy bandwidth (default: true when proxy is enabled) */
+  blockProxyResources?: boolean
+  token?: string
+}): Promise<{ id: string; liveUrl: string | null }> {
+  const client = getCloudClient()
+  if (!client) {
+    throw new Error('Not logged in to cloud. Run `playwriter cloud login` first.')
+  }
+
+  const connectResult = await client.connect({
+    proxyRegion,
+    customProxy: customProxy ? parseCustomProxy(customProxy) : undefined,
+    timeout,
+  })
+
+  if (!connectResult.cdpUrl) {
+    throw new Error('Cloud browser returned no CDP URL. The VM may have failed to start.')
+  }
+
+  // Normalize https:// CDP URL to wss:// for the relay
+  const cdpEndpoint = await resolveDirectInput(connectResult.cdpUrl)
+
+  // Create a playwriter session via the relay using the CDP URL (same as --direct).
+  // Also pass cloud metadata so the relay can track idle timeout and auto-disconnect.
+  const auth = loadCloudAuth()!
+  const cwd = process.cwd()
+  let response: Response
+  try {
+    response = await fetch(`${serverUrl}/cli/session/new`, {
+      method: 'POST',
+      headers: buildAuthHeaders({ token, json: true }),
+      body: JSON.stringify({
+        cdpEndpoint,
+        cwd,
+        browser: 'Chromium (cloud)',
+        cloud: {
+          cloudSessionId: connectResult.cloudSessionId,
+          cloudBaseUrl: auth.baseUrl,
+          cloudToken: auth.token,
+          timeoutAt: connectResult.timeoutAt,
+          blockProxyResources,
+        },
+      }),
+    })
+  } catch (cause) {
+    // Relay session creation failed — stop the cloud VM so we don't leak a paid resource
+    await client.disconnect(connectResult.cloudSessionId).catch(() => {})
+    throw new Error('Failed to create relay session', { cause })
+  }
+
+  if (!response.ok) {
+    await client.disconnect(connectResult.cloudSessionId).catch(() => {})
+    const text = await response.text()
+    throw new Error(`${response.status} ${text}`)
+  }
+  const result = (await response.json()) as { id: string }
+
+  return { id: result.id, liveUrl: connectResult.cdpUrl ? buildLiveUrl(connectResult.cdpUrl, auth.baseUrl) : null }
+}
+
+/** Reattach to an existing running cloud browser VM instead of creating a new one.
+ *  Fetches the session's cdpUrl from the cloud API and creates a relay session. */
+async function attachExistingCloudSession({
+  serverUrl,
+  cloudSessionId,
+  blockProxyResources,
+  token,
+}: {
+  serverUrl: string
+  cloudSessionId: string
+  blockProxyResources?: boolean
+  token?: string
+}): Promise<{ id: string; liveUrl: string | null }> {
+  const client = getCloudClient()
+  if (!client) {
+    throw new Error('Not logged in to cloud. Run `playwriter cloud login` first.')
+  }
+
+  const session = await client.getSessionStatus(cloudSessionId)
+  if (!session || session.status !== 'active') {
+    throw new Error('Cloud session is no longer active. It may have timed out.')
+  }
+  if (!session.cdpUrl) {
+    throw new Error('Cloud session has no CDP URL available.')
+  }
+
+  const cdpEndpoint = await resolveDirectInput(session.cdpUrl)
+  const auth = loadCloudAuth()!
+  const cwd = process.cwd()
+
+  const response = await fetch(`${serverUrl}/cli/session/new`, {
+    method: 'POST',
+    headers: buildAuthHeaders({ token, json: true }),
+    body: JSON.stringify({
+      cdpEndpoint,
+      cwd,
+      browser: 'Chromium (cloud)',
+      cloud: {
+        cloudSessionId,
+        cloudBaseUrl: auth.baseUrl,
+        cloudToken: auth.token,
+        timeoutAt: session.timeoutAt,
+        blockProxyResources,
+      },
+    }),
+  })
+
+  if (!response.ok) {
+    const text = await response.text()
+    throw new Error(`${response.status} ${text}`)
+  }
+  const result = (await response.json()) as { id: string }
+
+  return { id: result.id, liveUrl: session.cdpUrl ? buildLiveUrl(session.cdpUrl, auth.baseUrl) : null }
+}
+
 function printBrowserTable(options: BrowserOption[]): void {
   const typeLabels = options.map((opt) => {
-    return opt.type === 'direct' ? '--direct' : opt.type
+    if (opt.type === 'direct') return '--direct'
+    if (opt.type === 'cloud') return 'cloud'
+    return opt.type
   })
   const keyWidth = Math.max(3, ...options.map((opt) => opt.key.length))
   const typeWidth = Math.max(4, ...typeLabels.map((t) => t.length))
@@ -661,7 +1089,7 @@ cli
   .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
   .action(async (options) => {
     if (!options.host && !process.env.PLAYWRITER_HOST) {
-      await ensureRelayServer({ logger: console, env: cliRelayEnv })
+      await ensureRelayServer({ logger: console })
     }
 
     const serverUrl = await getServerUrl(options.host)
@@ -754,7 +1182,7 @@ cli
     const serverUrl = await getServerUrl(options.host)
 
     if (!options.host && !process.env.PLAYWRITER_HOST) {
-      await ensureRelayServer({ logger: console, env: cliRelayEnv })
+      await ensureRelayServer({ logger: console })
     }
 
     try {
@@ -786,7 +1214,7 @@ cli
     const serverUrl = await getServerUrl(options.host)
 
     if (!options.host && !process.env.PLAYWRITER_HOST) {
-      await ensureRelayServer({ logger: console, env: cliRelayEnv })
+      await ensureRelayServer({ logger: console })
     }
 
     try {
@@ -926,7 +1354,7 @@ cli
 
     // Start relay if local so the extension can connect, then fetch in parallel
     if (isLocal) {
-      await ensureRelayServer({ logger: console, env: cliRelayEnv })
+      await ensureRelayServer({ logger: console })
     }
 
     const [extensions, directInstances] = await Promise.all([
@@ -936,6 +1364,24 @@ cli
       isLocal ? discoverChromeInstances() : Promise.resolve([] as DiscoveredInstance[]),
     ])
 
+    const cloudOptions = await discoverCloudBrowsers()
+
+    // Check if a Chrome binary is available for headless mode
+    const headlessOption: BrowserOption[] = await (async () => {
+      try {
+        const { resolveBrowserExecutablePath } = await import('./browser-config.js')
+        resolveBrowserExecutablePath()
+        return [{
+          key: 'headless',
+          type: 'headless' as const,
+          browser: 'Chrome (Headless)',
+          profile: '-',
+        }]
+      } catch {
+        return []
+      }
+    })()
+
     const allOptions: BrowserOption[] = [
       ...extensions.map((ext) => {
         return {
@@ -947,12 +1393,16 @@ cli
         }
       }),
       ...directInstances.map(instanceToBrowserOption),
+      ...headlessOption,
+      ...cloudOptions,
     ]
 
     if (allOptions.length === 0) {
       console.log('No browsers detected.\n')
       console.log('  Extension: click the Playwriter icon on a tab to connect')
       console.log('  Direct:    open chrome://inspect/#remote-debugging in Chrome')
+      console.log('  Headless:  run `playwriter browser install` then `--browser headless`')
+      console.log('  Cloud:     run `playwriter cloud login` to connect cloud browsers')
       return
     }
 
@@ -968,6 +1418,182 @@ cli
     } else {
       console.log(pc.dim('Use with: playwriter session new [--browser <key>]'))
     }
+
+    const hasCloud = allOptions.some((opt) => {
+      return opt.type === 'cloud'
+    })
+    if (!hasCloud) {
+      printCloudTip()
+    }
+  })
+
+// ── Cloud commands ──────────────────────────────────────────────────
+
+cli
+  .command('cloud login', 'Authenticate with playwriter.dev to use cloud browsers')
+  .option('--base-url <url>', 'Website base URL (default: https://playwriter.dev)')
+  .action(async (options) => {
+    const baseUrl = options.baseUrl || process.env.PLAYWRITER_CLOUD_URL || 'https://playwriter.dev'
+
+    // Use the better-auth client SDK so we don't hardcode endpoint URLs.
+    // Hardcoded URLs broke before when better-auth changed paths between versions.
+    const { createAuthClient } = await import('better-auth/client')
+    const { deviceAuthorizationClient } = await import('better-auth/client/plugins')
+    const client = createAuthClient({
+      baseURL: baseUrl,
+      plugins: [deviceAuthorizationClient()],
+    })
+
+    console.log('Requesting device authorization...')
+    const { data: deviceData, error: requestError } = await client.device.code({
+      client_id: 'playwriter-cli',
+    })
+    if (requestError || !deviceData) {
+      console.error(`Error: failed to request device code — ${requestError?.error_description || requestError?.error || 'unknown error'}`)
+      process.exit(1)
+    }
+
+    const verificationUrl = deviceData.verification_uri_complete || `${baseUrl}/device?user_code=${deviceData.user_code}`
+    console.log(`\nOpen this URL in your browser:\n  ${verificationUrl}\n`)
+    console.log(`Code: ${deviceData.user_code}\n`)
+
+    await openInBrowser(verificationUrl)
+
+    console.log('Waiting for approval...')
+    const pollInterval = (deviceData.interval || 5) * 1000
+    const deadline = Date.now() + (deviceData.expires_in || 300) * 1000
+
+    while (Date.now() < deadline) {
+      await new Promise((r) => { setTimeout(r, pollInterval) })
+      const { data: tokenData, error: pollError } = await client.device.token({
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+        device_code: deviceData.device_code,
+        client_id: 'playwriter-cli',
+      })
+      if (tokenData?.access_token) {
+        saveCloudAuth({ token: tokenData.access_token, baseUrl })
+        console.log(pc.green('\nLogged in successfully!'))
+        console.log('Cloud browsers will now appear in `playwriter session new`.')
+        return
+      }
+      if (pollError?.error === 'authorization_pending' || pollError?.error === 'slow_down') {
+        continue
+      }
+      if (pollError) {
+        console.error(`\nError: Device authorization failed — ${pollError.error_description || pollError.error}`)
+        process.exit(1)
+      }
+    }
+
+    console.error('\nError: Device authorization timed out.')
+    process.exit(1)
+  })
+
+cli
+  .command('cloud subscribe', 'Open the subscription page to purchase cloud browser sessions')
+  .action(async () => {
+    const auth = loadCloudAuth()
+    if (!auth) {
+      console.error('Not logged in. Run `playwriter cloud login` first.')
+      process.exit(1)
+    }
+    const subscribeUrl = new URL('/dashboard', auth.baseUrl).toString()
+    console.log(`Open your browser to manage your subscription:\n  ${subscribeUrl}\n`)
+    await openInBrowser(subscribeUrl)
+  })
+
+cli
+  .command('cloud status', 'Show active cloud browser sessions')
+  .action(async () => {
+    const client = getCloudClient()
+    if (!client) {
+      console.error('Not logged in. Run `playwriter cloud login` first.')
+      process.exit(1)
+    }
+
+    try {
+      const { sessions } = await client.getStatus()
+
+      if (sessions.length === 0) {
+        console.log('No active cloud sessions.')
+        console.log(pc.dim('Start one with: playwriter session new --browser cloud'))
+        return
+      }
+
+      const keyWidth = Math.max(3, ...sessions.map((s) => `cloud-${s.index}`.length))
+      console.log('KEY'.padEnd(keyWidth) + '  ' + 'STATUS'.padEnd(10) + '  ' + 'DETAILS')
+      console.log('-'.repeat(keyWidth + 30))
+
+      for (const s of sessions) {
+        const key = `cloud-${s.index}`
+        const timeoutAt = new Date(s.timeoutAt).toLocaleTimeString()
+        console.log(
+          key.padEnd(keyWidth) +
+            '  ' +
+            pc.green('running'.padEnd(10)) +
+            '  ' +
+            `expires ${timeoutAt}`,
+        )
+      }
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error)
+      console.error(`Error: ${msg}`)
+      process.exit(1)
+    }
+  })
+
+cli
+  .command('cloud live [key]', 'Open a live browser view for an active cloud session')
+  .action(async (key) => {
+    const client = getCloudClient()
+    if (!client) {
+      console.error('Not logged in. Run `playwriter cloud login` first.')
+      process.exit(1)
+    }
+
+    try {
+      const { sessions } = await client.getStatus()
+      if (sessions.length === 0) {
+        console.log('No active cloud sessions.')
+        console.log(pc.dim('Start one with: playwriter session new --browser cloud'))
+        process.exit(1)
+      }
+
+      let session: (typeof sessions)[number] | undefined
+      if (key) {
+        // Match by cloud-N key or by cloudSessionId
+        session = sessions.find((s) => {
+          return `cloud-${s.index}` === key || s.cloudSessionId === key || s.browserUseSessionId === key
+        })
+        if (!session) {
+          console.error(`No active session matching "${key}".`)
+          console.error('Active sessions: ' + sessions.map((s) => { return `cloud-${s.index}` }).join(', '))
+          process.exit(1)
+        }
+      } else if (sessions.length === 1) {
+        session = sessions[0]!
+      } else {
+        console.log('Multiple active sessions. Specify one:\n')
+        for (const s of sessions) {
+          console.log(`  cloud-${s.index}  (expires ${new Date(s.timeoutAt).toLocaleTimeString()})`)
+        }
+        console.log(`\nUsage: playwriter cloud live cloud-1`)
+        process.exit(1)
+      }
+
+      if (!session.cdpUrl) {
+        console.error('Session has no CDP URL — it may still be starting.')
+        process.exit(1)
+      }
+      const auth = loadCloudAuth()!
+      const liveUrl = buildLiveUrl(session.cdpUrl, auth.baseUrl)
+      console.log(liveUrl)
+      await openInBrowser(liveUrl)
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error)
+      console.error(`Error: ${msg}`)
+      process.exit(1)
+    }
   })
 
 cli.command('logfile', 'Print the path to the relay server log file').action(() => {