playwriter 0.3.0 → 0.4.0

package/dist/cli.js

@@ -3,7 +3,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';
 // Prevent Buffers from dumping hex bytes in util.inspect output.
@@ -15,8 +15,8 @@ import { canEmitKittyGraphics, emitKittyImage } from './kitty-graphics.js';
 import { VERSION, LOG_FILE_PATH, LOG_CDP_FILE_PATH, parseRelayHost } from './utils.js';
 import { ensureRelayServer, RELAY_PORT, waitForConnectedExtensions, getExtensionOutdatedWarning, getExtensionStatus, } from './relay-client.js';
 import { discoverChromeInstances, resolveDirectInput } from './chrome-discovery.js';
+import { getCloudClient, loadCloudAuth, saveCloudAuth, buildLiveUrl } from './cloud-client.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const cliRelayEnv = { PLAYWRITER_AUTO_ENABLE: '1' };
 const cli = goke('playwriter');
 cli
     .command('browser start [binaryPath]', 'Start Chromium or Chrome for Testing with the bundled Playwriter extension')
@@ -38,7 +38,7 @@ cli
             import('./browser-config.js'),
             import('./package-paths.js'),
         ]);
-        await ensureRelayServer({ logger: console, env: cliRelayEnv });
+        await ensureRelayServer({ logger: console });
         const browserPath = resolveBrowserExecutablePath({ browserPath: binaryPath });
         const extensionPath = getBundledExtensionPath();
         const userDataDir = path.resolve(options.userDataDir || getDefaultBrowserUserDataDir());
@@ -77,6 +77,18 @@ cli
         process.exit(1);
     }
 });
+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) {
+        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)')
@@ -84,8 +96,12 @@ 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);
@@ -192,7 +208,7 @@ async function executeCode(options) {
     const serverUrl = await getServerUrl(host);
     // 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,
@@ -261,6 +277,9 @@ 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);
         }
@@ -281,10 +300,59 @@ 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());
+            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) {
+            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)
@@ -344,6 +412,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);
@@ -361,7 +430,7 @@ cli
     // Default mode: extension-based (existing behavior)
     let extensions = [];
     if (isLocal) {
-        await ensureRelayServer({ logger: console, env: cliRelayEnv });
+        await ensureRelayServer({ logger: console });
         extensions = await waitForConnectedExtensions({
             timeoutMs: 12000,
             pollIntervalMs: 250,
@@ -380,8 +449,54 @@ cli
         extensions = await fetchExtensionsStatus({ host: options.host, token: options.token });
     }
     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 = [...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);
     }
     // Warn if any connected extension was built with an older playwriter version
@@ -404,7 +519,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();
@@ -413,6 +528,7 @@ cli
             }
             const result = (await response.json());
             console.log(`Session ${result.id} created. Use with: playwriter -s ${result.id} -e "..."`);
+            printCloudTip();
         }
         catch (error) {
             console.error(`Error: ${error.message}`);
@@ -420,12 +536,14 @@ 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 = [
         ...extensions.map((ext) => {
             return {
@@ -439,19 +557,43 @@ cli
         ...directInstances.map((instance) => {
             return instanceToBrowserOption(instance);
         }),
+        ...cloudOptions,
     ];
     if (options.browser) {
         const selected = allOptions.find((opt) => {
             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);
         }
         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.'));
@@ -461,7 +603,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();
@@ -470,6 +612,7 @@ cli
                 }
                 const result = (await response.json());
                 console.log(`Session ${result.id} created. Use with: playwriter -s ${result.id} -e "..."`);
+                printCloudTip();
             }
         }
         catch (error) {
@@ -486,7 +629,7 @@ cli
 });
 async function ensureRelayForSessionCreation(isLocal) {
     if (isLocal) {
-        await ensureRelayServer({ logger: console, env: cliRelayEnv });
+        await ensureRelayServer({ logger: console });
     }
 }
 async function createDirectSession({ serverUrl, cdpEndpoint, browser, profiles, token, }) {
@@ -522,9 +665,248 @@ function formatInstanceProfiles(instance) {
     })
         .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() {
+    const client = getCloudClient();
+    if (!client)
+        return [];
+    try {
+        const { sessions } = await client.getStatus();
+        const options = sessions.map((s) => {
+            return {
+                key: `cloud-${s.index}`,
+                type: 'cloud',
+                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',
+            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) {
+    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, { hasCloudOptions }) {
+    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() {
+    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) {
+    // Format: [user:pass@]host:port
+    const atIdx = proxyStr.lastIndexOf('@');
+    let hostPort;
+    let username;
+    let password;
+    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) {
+    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, }) {
+    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;
+    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());
+    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, }) {
+    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());
+    return { id: result.id, liveUrl: session.cdpUrl ? buildLiveUrl(session.cdpUrl, auth.baseUrl) : null };
+}
 function printBrowserTable(options) {
     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));
@@ -548,7 +930,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);
     let sessions = [];
@@ -614,7 +996,7 @@ cli
     .action(async (sessionId, options) => {
     const serverUrl = await getServerUrl(options.host);
     if (!options.host && !process.env.PLAYWRITER_HOST) {
-        await ensureRelayServer({ logger: console, env: cliRelayEnv });
+        await ensureRelayServer({ logger: console });
     }
     try {
         const response = await fetch(`${serverUrl}/cli/session/delete`, {
@@ -642,7 +1024,7 @@ cli
     const cwd = process.cwd();
     const serverUrl = await getServerUrl(options.host);
     if (!options.host && !process.env.PLAYWRITER_HOST) {
-        await ensureRelayServer({ logger: console, env: cliRelayEnv });
+        await ensureRelayServer({ logger: console });
     }
     try {
         const response = await fetch(`${serverUrl}/cli/reset`, {
@@ -759,7 +1141,7 @@ cli
     const isLocal = !options.host && !process.env.PLAYWRITER_HOST;
     // 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([
         isLocal
@@ -767,6 +1149,23 @@ cli
             : fetchExtensionsStatus({ host: options.host, token: options.token }),
         isLocal ? discoverChromeInstances() : Promise.resolve([]),
     ]);
+    const cloudOptions = await discoverCloudBrowsers();
+    // Check if a Chrome binary is available for headless mode
+    const headlessOption = await (async () => {
+        try {
+            const { resolveBrowserExecutablePath } = await import('./browser-config.js');
+            resolveBrowserExecutablePath();
+            return [{
+                    key: 'headless',
+                    type: 'headless',
+                    browser: 'Chrome (Headless)',
+                    profile: '-',
+                }];
+        }
+        catch {
+            return [];
+        }
+    })();
     const allOptions = [
         ...extensions.map((ext) => {
             return {
@@ -778,11 +1177,15 @@ 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;
     }
     printBrowserTable(allOptions);
@@ -797,6 +1200,164 @@ 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;
+        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(() => {
     console.log(`relay: ${LOG_FILE_PATH}`);