tabwright 1.0.0

package/dist/cli.js

@@ -0,0 +1,2709 @@
+#!/usr/bin/env node
+import './env-compat.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import util from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { goke, openInBrowser } from 'goke';
+import { z } from 'zod';
+import pc from 'picocolors';
+// Prevent Buffers from dumping hex bytes in util.inspect output.
+Buffer.prototype[util.inspect.custom] = function () {
+    return `<Buffer ${this.length} bytes>`;
+};
+import { killPortProcess } from './kill-port.js';
+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, getExtensionsStatus, getLocalRelayHttpBaseUrl, getRelayServerFeatures, getRelayServerVersion, selectImplicitExtension, } from './relay-client.js';
+import { discoverChromeInstances, resolveDirectInput } from './chrome-discovery.js';
+import { getCloudClient, loadCloudAuth, saveCloudAuth, buildLiveUrl } from './cloud-client.js';
+import { createCapability, getCapabilitySafetySummary, listCapabilities, readCapabilityScript, routeCapabilities, searchCapabilities, toCapabilityContract, toCapabilitySummary, updateCapabilityManifest, updateCapabilityScript, } from './capability-registry.js';
+import { initCapabilityAgentSkill, installCapabilityAgentSkill, showCapabilityAgentSkill } from './capability-agent-skill.js';
+import { getTabwrightAgentSkillStatus, installTabwrightAgentSkill, } from './tabwright-agent-skill.js';
+import { installCapabilityPackage, packCapability } from './capability-package.js';
+import { refreshCapabilityAuthWithExecutor } from './capability-auth.js';
+import { finalizeCapabilityRun, normalizeCapabilityExecutionText, prepareCapabilityRun, readCapabilityExecutionObservation, runNodeCapability, } from './capability-runner.js';
+import { installBuiltinCapabilitySuite, isBuiltinCapabilitySuite } from './builtin-capabilities.js';
+import { createReplayAiIndexFromRecording, saveReplayAiIndex } from './replay-ai-index.js';
+import { listSavedRrwebRecordings } from './rrweb-recording-relay.js';
+import { compileReplayWorkflow, UnsupportedReplayWorkflowError, } from './replay-workflow-compiler.js';
+import { buildReplayCreateCommand, buildReplayIndexCommand, buildReplayMakeCommand, buildReplayRunCommand, replayCapabilityId, toCompactReplayAiIndex, } from './replay-handoff.js';
+import { formatReplayEvalReport, runReplayEval } from './replay-eval.js';
+import { buildDoctorReport, formatDoctorReport } from './doctor.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const cli = goke('tabwright');
+cli.on('command:*', () => {
+    const firstArg = cli.args[0];
+    if (!firstArg) {
+        return;
+    }
+    const hasMatchingCommandPrefix = cli.commands.some((command) => {
+        if (command.name === '') {
+            return false;
+        }
+        return command.name.split(' ')[0] === firstArg;
+    });
+    if (hasMatchingCommandPrefix) {
+        return;
+    }
+    console.error('Run "tabwright --help" for usage information.');
+});
+cli
+    .command('browser start [binaryPath]', 'Start Chromium or Chrome for Testing with the bundled Tabwright extension')
+    .hidden()
+    .option('--user-data-dir <dir>', 'Persistent browser profile directory used for the managed browser')
+    .option('--headless', 'Run the browser in headless mode')
+    .option('--headed', 'Force headed mode even on Linux without DISPLAY/WAYLAND_DISPLAY')
+    .option('--disable-sandbox', 'Disable the browser sandbox, useful on some VPS setups')
+    .action(async (binaryPath, options) => {
+    if (options.headless && options.headed) {
+        console.error('Error: --headless and --headed cannot be used together.');
+        process.exit(1);
+    }
+    try {
+        // Avoid loading playwright-core during generic CLI startup/help. This command
+        // is the only path that needs browser discovery and bundled extension launch.
+        const [{ getBrowserLaunchArgs, getDefaultBrowserUserDataDir, startBrowserProcess }, { resolveBrowserExecutablePath, shouldUseHeadlessByDefault }, { getBundledExtensionPath }] = await Promise.all([
+            import('./browser-launch.js'),
+            import('./browser-config.js'),
+            import('./package-paths.js'),
+        ]);
+        await ensureRelayServer({ logger: console });
+        const browserPath = resolveBrowserExecutablePath({ browserPath: binaryPath });
+        const extensionPath = getBundledExtensionPath();
+        const userDataDir = path.resolve(options.userDataDir || getDefaultBrowserUserDataDir());
+        const headless = options.headed ? false : options.headless ? true : shouldUseHeadlessByDefault();
+        const args = getBrowserLaunchArgs({
+            extensionPath,
+            userDataDir,
+            headless,
+            noSandbox: options.disableSandbox,
+        });
+        const { pid } = startBrowserProcess({
+            browserPath,
+            args,
+            userDataDir,
+        });
+        const connectedExtensions = await waitForConnectedExtensions({
+            timeoutMs: 15000,
+            pollIntervalMs: 250,
+            logger: console,
+        });
+        console.log(`Browser started (pid ${pid}).`);
+        console.log(`  Binary: ${browserPath}`);
+        console.log(`  Extension: ${extensionPath}`);
+        console.log(`  Profile: ${userDataDir}`);
+        console.log(`  Mode: ${headless ? 'headless' : 'headed'}`);
+        console.log('  Replay recording: rrweb DOM capture enabled');
+        if (connectedExtensions.length > 0) {
+            console.log('Tabwright extension connected to the relay server.');
+            return;
+        }
+        console.log('Browser started, but the extension has not connected yet.');
+        console.log(`Check logs at: ${LOG_FILE_PATH}`);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        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 TABWRIGHT_HOST env var)')
+    .option('--token <token>', 'Authentication token (or use TABWRIGHT_TOKEN env var)')
+    .option('-s, --session <name>', 'Session ID (required for -e, get one with `tabwright 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.TABWRIGHT_PATCHRIGHT = '1';
+    }
+    if (options.eval && options.file) {
+        console.error('Error: -e and -f cannot be used together.');
+        process.exit(1);
+    }
+    // If -e or -f flag is provided, execute code via relay server
+    const code = (() => {
+        if (options.eval) {
+            return options.eval;
+        }
+        if (options.file) {
+            const filePath = path.resolve(options.file);
+            if (!fs.existsSync(filePath)) {
+                console.error(`Error: File not found: ${filePath}`);
+                process.exit(1);
+            }
+            return fs.readFileSync(filePath, 'utf-8');
+        }
+        return null;
+    })();
+    if (code) {
+        await executeCode({
+            code,
+            timeout: options.timeout || 10000,
+            sessionId: options.session,
+            host: options.host,
+            token: options.token,
+        });
+        return;
+    }
+    // Otherwise start the MCP server
+    // For direct CDP in MCP mode, use TABWRIGHT_DIRECT env var
+    const { startMcp } = await import('./mcp.js');
+    await startMcp({
+        host: options.host,
+        token: options.token,
+    });
+});
+async function getServerUrl(host) {
+    if (!host && !process.env.TABWRIGHT_HOST) {
+        return await getLocalRelayHttpBaseUrl(RELAY_PORT);
+    }
+    const serverHost = host || process.env.TABWRIGHT_HOST || '127.0.0.1';
+    const { httpBaseUrl } = parseRelayHost(serverHost, RELAY_PORT);
+    return httpBaseUrl;
+}
+// Centralized header builder so every CLI subcommand sends the token consistently.
+// Falls back to TABWRIGHT_TOKEN env var when --token is not provided.
+function buildAuthHeaders({ token, json }) {
+    const headers = {};
+    if (json) {
+        headers['Content-Type'] = 'application/json';
+    }
+    const effectiveToken = token || process.env.TABWRIGHT_TOKEN;
+    if (effectiveToken) {
+        headers['Authorization'] = `Bearer ${effectiveToken}`;
+    }
+    return headers;
+}
+async function fetchExtensionsStatus({ host, token } = {}) {
+    try {
+        const serverUrl = await getServerUrl(host);
+        const headers = buildAuthHeaders({ token });
+        const response = await fetch(`${serverUrl}/extensions/status`, {
+            signal: AbortSignal.timeout(2000),
+            headers,
+        });
+        if (!response.ok) {
+            const fallback = await fetch(`${serverUrl}/extension/status`, {
+                signal: AbortSignal.timeout(2000),
+                headers,
+            });
+            if (!fallback.ok) {
+                return [];
+            }
+            const fallbackData = (await fallback.json());
+            if (!fallbackData?.connected) {
+                return [];
+            }
+            return [
+                {
+                    extensionId: 'default',
+                    stableKey: undefined,
+                    browser: fallbackData?.browser,
+                    profile: fallbackData?.profile,
+                    activeTargets: fallbackData?.activeTargets,
+                    playwriterVersion: fallbackData?.playwriterVersion || null,
+                    protocolVersion: fallbackData?.protocolVersion,
+                    features: fallbackData?.features,
+                    connectionHealth: fallbackData?.connectionHealth,
+                    missingFeatures: fallbackData?.missingFeatures,
+                },
+            ];
+        }
+        const data = (await response.json());
+        return data?.extensions || [];
+    }
+    catch {
+        return [];
+    }
+}
+async function executeCode(options) {
+    const { code, timeout, host, token } = options;
+    const cwd = process.cwd();
+    const sessionId = options.sessionId ? String(options.sessionId) : process.env.TABWRIGHT_SESSION;
+    // Session is required
+    if (!sessionId) {
+        console.error('Error: -s/--session is required.');
+        console.error('Always run `tabwright session new` first to get a session ID to use.');
+        process.exit(1);
+    }
+    // Ensure relay server is running (only for local)
+    if (!host && !process.env.TABWRIGHT_HOST) {
+        const restarted = await ensureRelayServer({ logger: console });
+        if (restarted) {
+            const connectedExtensions = await waitForConnectedExtensions({
+                logger: console,
+                timeoutMs: 10000,
+                pollIntervalMs: 250,
+            });
+            if (connectedExtensions.length === 0) {
+                console.error('Warning: Extension not connected. Commands may fail.');
+            }
+        }
+    }
+    const serverUrl = await getServerUrl(host);
+    // Warn once if extension is outdated
+    const extensionStatus = await getExtensionStatus();
+    const outdatedWarning = getExtensionOutdatedWarning(extensionStatus?.playwriterVersion);
+    if (outdatedWarning) {
+        console.error(outdatedWarning);
+    }
+    // Build request URL with token if provided
+    const executeUrl = `${serverUrl}/cli/execute`;
+    try {
+        const response = await fetch(executeUrl, {
+            method: 'POST',
+            headers: buildAuthHeaders({ token, json: true }),
+            body: JSON.stringify({ sessionId, code, timeout, cwd }),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            console.error(`Error: ${response.status} ${text}`);
+            process.exit(1);
+        }
+        const result = (await response.json());
+        // Print output
+        if (result.text) {
+            if (result.isError) {
+                console.error(result.text);
+            }
+            else {
+                console.log(result.text);
+            }
+        }
+        // Emit images via Kitty Graphics Protocol when AGENT_GRAPHICS=kitty.
+        // Agents with kitty-graphics-agent intercept these escape sequences and pass
+        // the PNG images to the LLM as media parts — no extra tool call needed.
+        const kittyEnabled = canEmitKittyGraphics();
+        // Track emitted base64 to avoid duplicates (screenshots appear in both
+        // result.screenshots and result.images from the same screenshotCollector)
+        const emittedImages = new Set();
+        if (result.screenshots && result.screenshots.length > 0) {
+            for (const s of result.screenshots) {
+                if (kittyEnabled && s.base64) {
+                    emitKittyImage({ base64: s.base64 });
+                    emittedImages.add(s.base64);
+                }
+                console.log(`\nScreenshot saved to: ${s.path}`);
+                console.log(`Labels shown: ${s.labelCount}\n`);
+                console.log(`Accessibility snapshot:\n${s.snapshot}`);
+            }
+        }
+        // Emit resized images from resizeImageForAgent() calls that aren't
+        // already emitted as part of labeled screenshots
+        if (kittyEnabled && result.images && result.images.length > 0) {
+            for (const img of result.images) {
+                if (img.data && !emittedImages.has(img.data)) {
+                    emitKittyImage({ base64: img.data });
+                    emittedImages.add(img.data);
+                }
+            }
+        }
+        if (result.isCloud) {
+            console.error(pc.dim(`\nCloud session. Run \`tabwright session delete ${sessionId}\` when done.`));
+        }
+        if (result.isError) {
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        if (error.cause?.code === 'ECONNREFUSED') {
+            console.error('Error: Cannot connect to relay server.');
+            console.error('The Tabwright relay server should start automatically. Check logs at:');
+            console.error(`  ${LOG_FILE_PATH}`);
+        }
+        else {
+            console.error(`Error: ${error.message}`);
+        }
+        process.exit(1);
+    }
+}
+function parseCapabilityInput(options) {
+    const rawInput = options.inputJson || options.input || '{}';
+    try {
+        return JSON.parse(rawInput);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON input: ${rawInput}`, { cause: error });
+    }
+}
+async function requestCliExecute(options) {
+    if (!options.host && !process.env.TABWRIGHT_HOST) {
+        await ensureRelayServer({ logger: console });
+    }
+    const serverUrl = await getServerUrl(options.host);
+    const response = await fetch(`${serverUrl}/cli/execute`, {
+        method: 'POST',
+        headers: buildAuthHeaders({ token: options.token, json: true }),
+        body: JSON.stringify({
+            sessionId: options.sessionId,
+            code: options.code,
+            timeout: options.timeout,
+            cwd: process.cwd(),
+            includeStructuredResult: options.includeStructuredResult,
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Execute failed: ${response.status} ${text}`);
+    }
+    return (await response.json());
+}
+async function createCapabilityRunSession(options) {
+    const isLocal = !options.host && !process.env.TABWRIGHT_HOST;
+    await ensureRelayForSessionCreation(isLocal);
+    const serverUrl = await getServerUrl(options.host);
+    const body = (() => {
+        if (options.browser === 'headless') {
+            return { headless: true, cwd: process.cwd() };
+        }
+        if (options.browser === 'user') {
+            return { cwd: process.cwd() };
+        }
+        return { extensionId: options.browser, cwd: process.cwd() };
+    })();
+    const response = await fetch(`${serverUrl}/cli/session/new`, {
+        method: 'POST',
+        headers: buildAuthHeaders({ token: options.token, json: true }),
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Failed to create ${options.browser} session: ${response.status} ${text}`);
+    }
+    const result = (await response.json());
+    return { sessionId: result.id, autoCreated: true };
+}
+async function deleteCapabilityRunSession(options) {
+    const serverUrl = await getServerUrl(options.host);
+    await fetch(`${serverUrl}/cli/session/delete`, {
+        method: 'POST',
+        headers: buildAuthHeaders({ token: options.token, json: true }),
+        body: JSON.stringify({ sessionId: options.sessionId }),
+    }).catch(() => { });
+}
+function printCapabilityList(options) {
+    if (options.json) {
+        console.log(JSON.stringify(options.capabilities.map(toCapabilitySummary), null, 2));
+        return;
+    }
+    if (options.capabilities.length === 0) {
+        console.log('No capabilities found.');
+        return;
+    }
+    const idWidth = Math.max(2, ...options.capabilities.map((capability) => capability.manifest.id.length));
+    const statusWidth = Math.max(6, ...options.capabilities.map((capability) => capability.manifest.status.length));
+    console.log(`${'ID'.padEnd(idWidth)}  ${'Status'.padEnd(statusWidth)}  Runtime  Location  Title`);
+    console.log(`${'-'.repeat(idWidth)}  ${'-'.repeat(statusWidth)}  -------  --------  -----`);
+    options.capabilities.forEach((capability) => {
+        console.log(`${capability.manifest.id.padEnd(idWidth)}  ${capability.manifest.status.padEnd(statusWidth)}  ${capability.manifest.runtime.padEnd(7)}  ${capability.location.padEnd(8)}  ${capability.manifest.title}`);
+    });
+}
+function printCapabilitySearch(options) {
+    if (options.json) {
+        console.log(JSON.stringify(options.results.map((result) => {
+            return {
+                score: result.score,
+                reasons: result.reasons,
+                ...toCapabilityContract(result.capability),
+            };
+        }), null, 2));
+        return;
+    }
+    if (options.results.length === 0) {
+        console.log(`No capabilities matched: ${options.query}`);
+        return;
+    }
+    const lines = options.results.map((result) => {
+        const safety = getCapabilitySafetySummary(result.capability);
+        const autonomy = safety.sideEffect === 'mixed' ? 'mixed' : safety.requiresConfirmation ? 'confirm' : safety.sideEffect;
+        return `${result.capability.manifest.id}  score=${result.score}  ${result.capability.manifest.runtime}/${autonomy}  ${result.capability.manifest.title}`;
+    });
+    console.log(lines.join('\n'));
+}
+function printCapabilityRoutes(options) {
+    const routeSummaries = options.routes.map((route) => {
+        return {
+            shellCommand: route.shellCommand,
+            command: route.command,
+            capabilityId: route.capability.manifest.id,
+            operation: route.operation,
+            id: route.capability.manifest.id,
+            title: route.capability.manifest.title,
+            location: route.capability.location,
+            routingHint: route.operation === undefined
+                ? route.capability.manifest.routingHint
+                : route.capability.manifest.operations[route.operation]?.routingHint,
+            input: route.input,
+            commandWarning: route.commandWarning,
+            executionHint: route.executionHint,
+            reasons: route.reasons,
+            matchedText: route.matchedText,
+        };
+    });
+    if (options.json) {
+        console.log(JSON.stringify(routeSummaries, null, 2));
+        return;
+    }
+    if (routeSummaries.length === 0) {
+        console.log(`No exact direct-run capability matched: ${options.task}`);
+        console.log(`Next: tabwright capability search ${quoteShell(options.task)}`);
+        return;
+    }
+    console.log(routeSummaries
+        .map((route) => {
+        return `run: ${route.shellCommand}\ncapabilityId: ${route.capabilityId}\nwarning: ${route.commandWarning}`;
+    })
+        .join('\n'));
+}
+function quoteShell(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function readCapabilityManifestPatchFromFile(filePath) {
+    const parsed = JSON.parse(fs.readFileSync(path.resolve(filePath), 'utf-8'));
+    if (!isRecord(parsed)) {
+        throw new Error('Capability contract file must contain a JSON object');
+    }
+    return parsed;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+async function refreshCapabilityAuthFromCli(id, options) {
+    const session = options.session || process.env.TABWRIGHT_SESSION;
+    const sessionInfo = session
+        ? { sessionId: session, autoCreated: false }
+        : await createCapabilityRunSession({
+            browser: options.browser || 'user',
+            host: options.host,
+            token: options.token,
+        });
+    try {
+        const result = await refreshCapabilityAuthWithExecutor({
+            id,
+            cwd: process.cwd(),
+            timeout: options.timeout || 10000,
+            executor: {
+                execute: (code, timeout, executeOptions) => {
+                    return requestCliExecute({
+                        code,
+                        timeout: timeout || 10000,
+                        sessionId: sessionInfo.sessionId,
+                        host: options.host,
+                        token: options.token,
+                        includeStructuredResult: executeOptions?.includeStructuredResult,
+                    });
+                },
+            },
+        });
+        if (options.json) {
+            console.log(JSON.stringify({
+                capability: result.capability.manifest.id,
+                saved: result.saved,
+                secretKey: result.secretKey,
+                cookieCount: result.cookieCount,
+                cookieNames: result.cookieNames,
+                urls: result.urls,
+                expiresAt: result.expiresAt,
+                path: result.path,
+            }, null, 2));
+            return;
+        }
+        console.log(`Refreshed ${result.capability.manifest.id} auth at ${result.path}`);
+        console.log(`Saved ${result.cookieCount} cookies into secret "${result.secretKey}".`);
+        if (result.expiresAt) {
+            console.log(`Expires at ${result.expiresAt}.`);
+        }
+    }
+    finally {
+        if (sessionInfo.autoCreated && !options.keepSession) {
+            await deleteCapabilityRunSession({
+                sessionId: sessionInfo.sessionId,
+                host: options.host,
+                token: options.token,
+            });
+        }
+    }
+}
+async function runCapabilityFromCli(id, options) {
+    const input = parseCapabilityInput({ input: options.input, inputJson: options.inputJson });
+    const prepared = prepareCapabilityRun({
+        id,
+        input,
+        cwd: process.cwd(),
+        force: options.force,
+        confirmation: options.confirm,
+    });
+    if (prepared.capability.manifest.runtime === 'node') {
+        const result = await runNodeCapability({
+            id,
+            input,
+            cwd: process.cwd(),
+            force: options.force,
+            confirmation: options.confirm,
+            timeout: options.timeout || 10000,
+        });
+        if (options.json) {
+            console.log(JSON.stringify({
+                capability: result.capability.manifest.id,
+                output: result.output,
+                text: result.text,
+                isError: result.isError,
+            }, null, 2));
+            return;
+        }
+        console.log(JSON.stringify(result.output, null, 2));
+        return;
+    }
+    const session = options.session || process.env.TABWRIGHT_SESSION;
+    const sessionInfo = session
+        ? { sessionId: session, autoCreated: false }
+        : await createCapabilityRunSession({
+            browser: options.browser || 'headless',
+            host: options.host,
+            token: options.token,
+        });
+    const start = Date.now();
+    try {
+        const result = await requestCliExecute({
+            code: prepared.code,
+            timeout: options.timeout || 10000,
+            sessionId: sessionInfo.sessionId,
+            host: options.host,
+            token: options.token,
+            includeStructuredResult: true,
+        }).catch((error) => {
+            finalizeCapabilityRun({
+                capability: prepared.capability,
+                operation: prepared.operation,
+                cwd: process.cwd(),
+                inputHash: prepared.inputHash,
+                startedAt: start,
+                execution: {
+                    status: 'error',
+                    output: undefined,
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+            throw error;
+        });
+        const observation = readCapabilityExecutionObservation(result.structuredResult);
+        const isExecutionError = result.isError || Boolean(observation.error);
+        const normalizedText = normalizeCapabilityExecutionText({
+            text: result.text,
+            output: observation.output,
+            error: observation.error,
+        });
+        const finalized = finalizeCapabilityRun({
+            capability: prepared.capability,
+            operation: prepared.operation,
+            cwd: process.cwd(),
+            inputHash: prepared.inputHash,
+            startedAt: start,
+            execution: {
+                status: isExecutionError ? 'error' : 'success',
+                output: observation.output,
+                error: isExecutionError ? observation.error || normalizedText : undefined,
+                observedNetworkUrls: observation.observedNetworkUrls,
+                url: observation.url,
+            },
+        });
+        if (finalized.contractError) {
+            throw finalized.contractError;
+        }
+        if (options.json) {
+            console.log(JSON.stringify({
+                capability: prepared.capability.manifest.id,
+                output: observation.output,
+                text: normalizedText,
+                isError: isExecutionError,
+            }, null, 2));
+        }
+        else {
+            console.log(JSON.stringify(observation.output, null, 2));
+            if (isExecutionError) {
+                console.error(normalizedText);
+            }
+        }
+        if (isExecutionError) {
+            process.exit(1);
+        }
+    }
+    finally {
+        if (sessionInfo.autoCreated && !options.keepSession) {
+            await deleteCapabilityRunSession({
+                sessionId: sessionInfo.sessionId,
+                host: options.host,
+                token: options.token,
+            });
+        }
+    }
+}
+function exitWithError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+}
+function buildNestedExampleInput(pathValue) {
+    const parts = pathValue.split('.').filter((part) => {
+        return part.length > 0;
+    });
+    if (parts.length === 0) {
+        return { value: '...' };
+    }
+    return parts.reduceRight((current, part) => {
+        if (typeof current === 'string') {
+            return { [part]: current };
+        }
+        return { [part]: current };
+    }, '...');
+}
+function toReplayCompilerSummary(analysis) {
+    return {
+        supported: analysis.actionKind !== 'unknown',
+        ...analysis,
+    };
+}
+function buildReplayNeedsAiHandoff(options) {
+    const index = createReplayAiIndexFromRecording(options.replayId);
+    return {
+        status: 'needs_ai',
+        replay: {
+            id: options.replayId,
+            url: index.url,
+        },
+        capabilityWritten: false,
+        compiler: toReplayCompilerSummary(options.analysis),
+        evidence: toCompactReplayAiIndex(index),
+        next: {
+            action: 'author_capability',
+            inspectCommand: buildReplayIndexCommand({ replayId: options.replayId, full: true }),
+            createCommand: buildReplayCreateCommand({
+                capabilityId: options.capabilityId,
+                title: `Workflow from replay ${options.replayId}`,
+                description: options.goal,
+            }),
+        },
+    };
+}
+function printReplayNeedsAiHandoff(options) {
+    if (options.json) {
+        console.log(JSON.stringify(options.handoff, null, 2));
+        return;
+    }
+    console.log(`Replay ${options.handoff.replay.id} needs AI authoring.`);
+    console.log('No capability was written.');
+    options.handoff.compiler.reasons.forEach((reason) => {
+        console.log(`- ${reason}`);
+    });
+    console.log(`Inspect full evidence: ${options.handoff.next.inspectCommand}`);
+    console.log(`Create a browser scaffold: ${options.handoff.next.createCommand}`);
+}
+cli
+    .command('replay list', 'List saved rrweb replays and the next commands for each recording')
+    .option('--limit <n>', z.number().default(10).describe('Maximum number of recordings'))
+    .option('--json', 'Print JSON')
+    .action((options) => {
+    try {
+        const recordings = listSavedRrwebRecordings({ limit: options.limit || 10 }).map((recording) => {
+            return {
+                id: recording.id,
+                url: recording.url,
+                savedAt: recording.savedAt,
+                durationMs: recording.duration,
+                eventCount: recording.eventCount,
+                commands: {
+                    inspect: buildReplayIndexCommand({ replayId: recording.id }),
+                    make: buildReplayMakeCommand({
+                        replayId: recording.id,
+                        capabilityId: replayCapabilityId(recording.id),
+                    }),
+                },
+            };
+        });
+        if (options.json) {
+            console.log(JSON.stringify({
+                recordings,
+                next: recordings.length > 0
+                    ? recordings[0]?.commands
+                    : { action: 'record', command: 'Use replay.start() and replay.stop() in a Tabwright session.' },
+            }, null, 2));
+            return;
+        }
+        if (recordings.length === 0) {
+            console.log('No saved replays. Use replay.start() and replay.stop() in a Tabwright session first.');
+            return;
+        }
+        recordings.forEach((recording) => {
+            console.log(`${recording.id}  ${recording.url || '-'}  ${recording.eventCount} events`);
+            console.log(`  Inspect: ${recording.commands.inspect}`);
+            console.log(`  Make: ${recording.commands.make}`);
+        });
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('replay index <replayId>', 'Build an AI-readable index from an rrweb replay')
+    .option('--write', 'Save the index under ~/.tabwright/replay-ai-indexes')
+    .option('--full', 'Include page text and the full interactive-element inventory')
+    .option('--json', 'Print JSON')
+    .action((replayId, options) => {
+    try {
+        const index = createReplayAiIndexFromRecording(replayId);
+        const saved = options.write ? saveReplayAiIndex(index) : undefined;
+        if (options.json) {
+            const outputIndex = options.full ? index : toCompactReplayAiIndex(index);
+            console.log(JSON.stringify(saved ? { index: outputIndex, saved } : { index: outputIndex }, null, 2));
+            return;
+        }
+        console.log(`Replay: ${index.replayId}`);
+        console.log(`URL: ${index.url || '-'}`);
+        console.log(`Actions: ${index.actions.length}`);
+        console.log(`Fields: ${index.fields.length}`);
+        console.log(`Annotations: ${index.annotations.length}`);
+        console.log(`Stats: ${JSON.stringify(index.stats)}`);
+        if (saved) {
+            console.log(`Saved: ${saved.path}`);
+        }
+        index.annotations.slice(0, 8).forEach((annotation, index) => {
+            const target = annotation.target?.label || annotation.target?.selectorHints[0] || annotation.target?.tagName || 'target';
+            console.log(`${index + 1}. ${pc.magenta('annotation')} ${target}: ${annotation.text}`);
+        });
+        index.actions.slice(0, 12).forEach((action, index) => {
+            const value = action.value === undefined ? '' : ` = ${JSON.stringify(action.value)}`;
+            console.log(`${index + 1}. ${pc.cyan(action.kind)} ${action.label}${value}`);
+        });
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('replay compile <replayId> <capabilityId>', 'Compile an rrweb replay into a draft workflow capability')
+    .option('--title <title>', 'Capability title')
+    .option('--description <description>', 'Capability description')
+    .option('--goal <goal>', 'User goal to store as capability description')
+    .option('--value-input-path <path>', 'Input path for the appended value (default: value)')
+    .option('--force', 'Overwrite an existing capability')
+    .option('--json', 'Print JSON')
+    .action((replayId, capabilityId, options) => {
+    try {
+        const valueInputPath = options.valueInputPath || 'value';
+        const compiled = compileReplayWorkflow({
+            replayId,
+            id: capabilityId,
+            cwd: process.cwd(),
+            title: options.title,
+            description: options.description || options.goal,
+            valueInputPath,
+            overwrite: options.force,
+        });
+        const runCommand = buildReplayRunCommand({
+            capabilityId,
+            input: buildNestedExampleInput(valueInputPath),
+        });
+        if (options.json) {
+            console.log(JSON.stringify({
+                status: 'compiled',
+                replay: {
+                    id: replayId,
+                    url: compiled.analysis.url,
+                },
+                compiler: toReplayCompilerSummary(compiled.analysis),
+                capability: compiled.saved.capability,
+                next: {
+                    requiresUserConfirmation: true,
+                    runCommand,
+                },
+            }, null, 2));
+            return;
+        }
+        console.log(`Compiled ${replayId} into ${capabilityId}`);
+        console.log(`Action: ${compiled.analysis.actionKind}`);
+        console.log(`Confidence: ${compiled.analysis.confidence}`);
+        console.log(`Observed value: ${compiled.analysis.demonstratedValue || '-'}`);
+        console.log('Requires explicit user confirmation before running.');
+        console.log(`After approval: ${runCommand}`);
+    }
+    catch (error) {
+        if (error instanceof UnsupportedReplayWorkflowError) {
+            printReplayNeedsAiHandoff({
+                handoff: buildReplayNeedsAiHandoff({
+                    replayId,
+                    capabilityId,
+                    goal: options.description || options.goal,
+                    analysis: error.analysis,
+                }),
+                json: options.json,
+            });
+            return;
+        }
+        exitWithError(error);
+    }
+});
+cli
+    .command('replay make <replayId> <capabilityId>', 'Index and compile a replay into a runnable draft capability')
+    .option('--title <title>', 'Capability title')
+    .option('--description <description>', 'Capability description')
+    .option('--goal <goal>', 'User goal to store as capability description')
+    .option('--value-input-path <path>', 'Input path for the appended value (default: value)')
+    .option('--write-index', 'Save the generated replay index under ~/.tabwright/replay-ai-indexes')
+    .option('--force', 'Overwrite an existing capability')
+    .option('--json', 'Print JSON')
+    .action((replayId, capabilityId, options) => {
+    try {
+        const valueInputPath = options.valueInputPath || 'value';
+        const index = createReplayAiIndexFromRecording(replayId);
+        const savedIndex = options.writeIndex ? saveReplayAiIndex(index) : undefined;
+        const compiled = compileReplayWorkflow({
+            replayId,
+            id: capabilityId,
+            cwd: process.cwd(),
+            title: options.title,
+            description: options.description || options.goal,
+            valueInputPath,
+            overwrite: options.force,
+        });
+        const runCommand = buildReplayRunCommand({
+            capabilityId,
+            input: buildNestedExampleInput(valueInputPath),
+        });
+        if (options.json) {
+            console.log(JSON.stringify({
+                status: 'compiled',
+                replay: {
+                    id: replayId,
+                    url: index.url,
+                },
+                savedIndex,
+                compiler: toReplayCompilerSummary(compiled.analysis),
+                evidence: toCompactReplayAiIndex(index),
+                capability: compiled.saved.capability,
+                next: {
+                    requiresUserConfirmation: true,
+                    runCommand,
+                },
+            }, null, 2));
+            return;
+        }
+        console.log(`Replay: ${index.replayId}`);
+        console.log(`URL: ${index.url || '-'}`);
+        console.log(`Actions: ${index.actions.length}`);
+        console.log(`Fields: ${index.fields.length}`);
+        console.log(`Annotations: ${index.annotations.length}`);
+        if (savedIndex) {
+            console.log(`Saved index: ${savedIndex.path}`);
+        }
+        console.log(`Compiled capability: ${capabilityId}`);
+        console.log(`Action: ${compiled.analysis.actionKind}`);
+        console.log(`Confidence: ${compiled.analysis.confidence}`);
+        console.log(`Observed value: ${compiled.analysis.demonstratedValue || '-'}`);
+        console.log('Requires explicit user confirmation before running.');
+        console.log(`After approval: ${runCommand}`);
+    }
+    catch (error) {
+        if (error instanceof UnsupportedReplayWorkflowError) {
+            printReplayNeedsAiHandoff({
+                handoff: buildReplayNeedsAiHandoff({
+                    replayId,
+                    capabilityId,
+                    goal: options.description || options.goal,
+                    analysis: error.analysis,
+                }),
+                json: options.json,
+            });
+            return;
+        }
+        exitWithError(error);
+    }
+});
+cli
+    .command('replay eval', 'Run replay-to-capability evaluation cases against local example pages')
+    .option('--case <id>', 'Run one evaluation case')
+    .option('--json', 'Print JSON')
+    .option('--report <path>', 'Write an HTML report')
+    .option('--keep-artifacts', 'Keep generated temporary recordings and capabilities')
+    .option('--headed', 'Run the evaluation browser in headed mode')
+    .action(async (options) => {
+    try {
+        const report = await runReplayEval({
+            caseId: options.case,
+            reportPath: options.report,
+            keepArtifacts: options.keepArtifacts,
+            headed: options.headed,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        console.log(formatReplayEvalReport(report));
+        if (options.report) {
+            console.log(`Report: ${path.resolve(options.report)}`);
+        }
+        if (report.failed > 0) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability list', 'List saved Tabwright capabilities')
+    .option('--json', 'Print JSON')
+    .action((options) => {
+    try {
+        printCapabilityList({ capabilities: listCapabilities({ cwd: process.cwd() }), json: options.json });
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability route <task>', 'Find an exact-match direct-run capability for a concrete task or URL')
+    .option('--limit <n>', z.number().default(3).describe('Maximum number of routes'))
+    .option('--json', 'Print JSON')
+    .action((task, options) => {
+    try {
+        printCapabilityRoutes({
+            task,
+            routes: routeCapabilities({ task, cwd: process.cwd(), limit: options.limit || 3 }),
+            json: options.json,
+        });
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability search <query>', 'Search saved Tabwright capabilities by user intent')
+    .option('--limit <n>', z.number().default(10).describe('Maximum number of results'))
+    .option('--json', 'Print JSON')
+    .action((query, options) => {
+    try {
+        printCapabilitySearch({
+            query,
+            results: searchCapabilities({ query, cwd: process.cwd(), limit: options.limit || 10 }),
+            json: options.json,
+        });
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability describe <id>', 'Print the AI-readable contract for a capability')
+    .option('--json', 'Print JSON')
+    .action((id, options) => {
+    try {
+        const capability = listCapabilities({ cwd: process.cwd() }).find((candidate) => {
+            return candidate.manifest.id === id;
+        });
+        if (!capability) {
+            throw new Error(`Capability not found: ${id}`);
+        }
+        const contract = toCapabilityContract(capability);
+        if (options.json) {
+            console.log(JSON.stringify(contract, null, 2));
+            return;
+        }
+        console.log(JSON.stringify(contract, null, 2));
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability show <id>', 'Show a saved Tabwright capability')
+    .option('--json', 'Print JSON')
+    .option('--script', 'Print the script source')
+    .action((id, options) => {
+    try {
+        const capability = listCapabilities({ cwd: process.cwd() }).find((candidate) => {
+            return candidate.manifest.id === id;
+        });
+        if (!capability) {
+            throw new Error(`Capability not found: ${id}`);
+        }
+        if (options.script) {
+            console.log(readCapabilityScript({ id, cwd: process.cwd() }));
+            return;
+        }
+        if (options.json) {
+            console.log(JSON.stringify(toCapabilitySummary(capability), null, 2));
+            return;
+        }
+        console.log(`${capability.manifest.title} (${capability.manifest.id})`);
+        console.log(`Status: ${capability.manifest.status}`);
+        console.log(`Runtime: ${capability.manifest.runtime}`);
+        console.log(`Location: ${capability.location}`);
+        console.log(`Directory: ${capability.dir}`);
+        if (capability.manifest.description) {
+            console.log(`Description: ${capability.manifest.description}`);
+        }
+        console.log(`Match: ${capability.manifest.match.length > 0 ? capability.manifest.match.join(', ') : '-'}`);
+        console.log(`Permissions: ${capability.manifest.permissions.join(', ') || '-'}`);
+        console.log(`Entry: ${capability.manifest.entry}`);
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability create <id>', 'Create a draft Tabwright capability')
+    .option('--title <title>', 'Capability title')
+    .option('--description <description>', 'Capability description')
+    .option('--project', 'Create under .tabwright/capabilities in the current project')
+    .option('--runtime <browser|node>', 'Capability runtime (default: browser)')
+    .option('--force', 'Overwrite an existing capability')
+    .option('--json', 'Print JSON')
+    .action((id, options) => {
+    try {
+        if (options.runtime && options.runtime !== 'browser' && options.runtime !== 'node') {
+            throw new Error(`Invalid runtime: ${options.runtime}`);
+        }
+        const runtime = options.runtime === 'browser' || options.runtime === 'node' ? options.runtime : undefined;
+        const capability = createCapability({
+            id,
+            title: options.title,
+            description: options.description,
+            location: options.project ? 'project' : 'user',
+            cwd: process.cwd(),
+            overwrite: options.force,
+            createdBy: 'ai',
+            runtime,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(toCapabilitySummary(capability), null, 2));
+            return;
+        }
+        console.log(`Created ${capability.manifest.id} at ${capability.dir}`);
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability skill init <id>', 'Create an editable agent skill scaffold for a saved capability')
+    .option('--force', 'Overwrite an existing agent skill draft')
+    .option('--json', 'Print JSON')
+    .action((id, options) => {
+    try {
+        const result = initCapabilityAgentSkill({
+            id,
+            cwd: process.cwd(),
+            overwrite: options.force,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Created agent skill draft for ${result.capabilityId}: ${result.dir}`);
+        result.files.forEach((file) => {
+            console.log(`- ${file.status}: ${file.path}`);
+        });
+        console.log('');
+        console.log('Next:');
+        result.next.forEach((step) => {
+            console.log(`  ${step}`);
+        });
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability skill install <id>', 'Install an edited capability agent skill into Codex')
+    .option('--force', 'Overwrite an existing installed agent skill')
+    .option('--codex-home <dir>', 'Codex home directory (defaults to CODEX_HOME or ~/.codex)')
+    .option('--json', 'Print JSON')
+    .action((id, options) => {
+    try {
+        const result = installCapabilityAgentSkill({
+            id,
+            cwd: process.cwd(),
+            overwrite: options.force,
+            codexHome: options.codexHome,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Installed agent skill for ${result.capabilityId}: ${result.dir}`);
+        result.files.forEach((file) => {
+            console.log(`- ${file.status}: ${file.path}`);
+        });
+        console.log('');
+        console.log('Next:');
+        result.next.forEach((step) => {
+            console.log(`  ${step}`);
+        });
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability skill show <id>', 'Show the editable agent skill draft for a saved capability')
+    .option('--json', 'Print JSON')
+    .action((id, options) => {
+    try {
+        const result = showCapabilityAgentSkill({
+            id,
+            cwd: process.cwd(),
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const skill = result.files.find((file) => {
+            return file.relativePath === 'SKILL.md';
+        });
+        if (!skill) {
+            throw new Error(`Agent skill draft missing SKILL.md for ${id}`);
+        }
+        console.log(skill.content);
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability pack <id>', 'Pack a capability for safe sharing')
+    .option('-o, --output <path>', 'Output .tgz path (default: <id>.tgz)')
+    .option('--force', 'Overwrite an existing package')
+    .option('--json', 'Print JSON')
+    .action(async (id, options) => {
+    try {
+        const packed = await packCapability({
+            id,
+            cwd: process.cwd(),
+            output: options.output,
+            overwrite: options.force,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(packed, null, 2));
+            return;
+        }
+        console.log(`Packed ${packed.capabilityId}: ${packed.path}`);
+        console.log(`Integrity: ${packed.integrity}`);
+        console.log('Included files:');
+        packed.files.map((file) => {
+            console.log(`- ${file}`);
+            return file;
+        });
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability install <source>', 'Install a built-in suite, capability directory, local .tgz, or .tgz URL')
+    .option('--project', 'Install under .tabwright/capabilities in the current project')
+    .option('--force', 'Overwrite existing installed capabilities')
+    .option('--draft', 'Install a built-in suite as draft instead of trusted')
+    .option('--skip-agent-skills', 'Do not install bundled agent skills such as Codex skills')
+    .option('--with-agent-skill', 'Install a shared package agent skill after reviewing the source')
+    .option('--json', 'Print JSON')
+    .action(async (source, options) => {
+    try {
+        if (isBuiltinCapabilitySuite(source)) {
+            const installed = installBuiltinCapabilitySuite({
+                suite: source,
+                cwd: process.cwd(),
+                location: options.project ? 'project' : 'user',
+                overwrite: options.force,
+                trust: options.draft ? false : true,
+                installAgentSkills: options.skipAgentSkills ? false : true,
+            });
+            const summary = {
+                type: 'builtin',
+                suite: installed.suite,
+                capabilities: installed.capabilities.map((capability) => {
+                    return toCapabilitySummary(capability);
+                }),
+                agentSkills: installed.agentSkills,
+                next: installed.capabilities.flatMap((capability) => {
+                    if (capability.manifest.auth.refresh !== 'from-browser') {
+                        return [];
+                    }
+                    return [`tabwright capability refresh-auth ${capability.manifest.id} --browser user --json`];
+                }),
+            };
+            if (options.json) {
+                console.log(JSON.stringify(summary, null, 2));
+                return;
+            }
+            console.log(`Installed ${installed.suite}:`);
+            installed.capabilities.map((capability) => {
+                console.log(`- ${capability.manifest.id} (${capability.location}, ${capability.manifest.status})`);
+                return capability.manifest.id;
+            });
+            if (installed.agentSkills.length > 0) {
+                console.log('');
+                console.log('Installed agent skills:');
+                installed.agentSkills.map((agentSkill) => {
+                    console.log(`- ${agentSkill.target}:${agentSkill.name} at ${agentSkill.dir}`);
+                    return agentSkill.name;
+                });
+            }
+            if (summary.next.length > 0) {
+                console.log('');
+                console.log('Refresh auth with:');
+                summary.next.map((command) => {
+                    console.log(`  ${command}`);
+                    return command;
+                });
+            }
+            return;
+        }
+        const installed = await installCapabilityPackage({
+            source,
+            cwd: process.cwd(),
+            location: options.project ? 'project' : 'user',
+            overwrite: options.force,
+        });
+        const agentSkill = installed.agentSkillAvailable && options.withAgentSkill
+            ? installCapabilityAgentSkill({
+                id: installed.capability.manifest.id,
+                cwd: process.cwd(),
+                overwrite: options.force,
+                capability: installed.capability,
+            })
+            : null;
+        const next = [
+            `tabwright capability describe ${installed.capability.manifest.id} --json`,
+            ...(installed.agentSkillAvailable && !agentSkill
+                ? [`Review the packaged agent skill, then install it with: tabwright capability skill install ${installed.capability.manifest.id}`]
+                : []),
+            ...(installed.capability.manifest.auth.refresh === 'from-browser'
+                ? [`tabwright capability refresh-auth ${installed.capability.manifest.id} --browser user --json`]
+                : []),
+            `Validate with capability run --force before trusting ${installed.capability.manifest.id}.`,
+        ];
+        const summary = {
+            type: 'package',
+            source: installed.source,
+            capability: toCapabilitySummary(installed.capability),
+            files: installed.files,
+            integrity: installed.integrity,
+            agentSkill,
+            next,
+        };
+        if (options.json) {
+            console.log(JSON.stringify(summary, null, 2));
+            return;
+        }
+        console.log(`Installed ${installed.capability.manifest.id} as draft: ${installed.capability.dir}`);
+        console.log(`Integrity: ${installed.integrity}`);
+        if (agentSkill) {
+            console.log(`Installed agent skill: ${agentSkill.dir}`);
+        }
+        console.log('');
+        console.log('Next:');
+        next.map((step) => {
+            console.log(`  ${step}`);
+            return step;
+        });
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability update <id>', 'Update a capability script from a file')
+    .option('--from-file <path>', 'Path to the new script.js source')
+    .option('--contract-file <path>', 'Path to a JSON manifest contract patch')
+    .option('--title <title>', 'Update title')
+    .option('--description <description>', 'Update description')
+    .option('--json', 'Print JSON')
+    .action((id, options) => {
+    try {
+        let capability = null;
+        if (options.fromFile) {
+            const sourcePath = path.resolve(options.fromFile);
+            capability = updateCapabilityScript({ id, cwd: process.cwd(), source: fs.readFileSync(sourcePath, 'utf-8') });
+        }
+        if (options.contractFile) {
+            const patch = readCapabilityManifestPatchFromFile(options.contractFile);
+            const currentCapability = capability ||
+                listCapabilities({ cwd: process.cwd() }).find((candidate) => {
+                    return candidate.manifest.id === id;
+                }) ||
+                null;
+            if (currentCapability?.manifest.status === 'trusted' && !patch.status) {
+                patch.status = 'draft';
+            }
+            capability = updateCapabilityManifest({ id, cwd: process.cwd(), patch });
+        }
+        if (options.title || options.description) {
+            const patch = {};
+            if (options.title) {
+                patch.title = options.title;
+            }
+            if (options.description) {
+                patch.description = options.description;
+            }
+            capability = updateCapabilityManifest({
+                id,
+                cwd: process.cwd(),
+                patch,
+            });
+        }
+        if (!capability) {
+            throw new Error('Nothing to update. Pass --from-file, --contract-file, --title, or --description.');
+        }
+        if (options.json) {
+            console.log(JSON.stringify(toCapabilitySummary(capability), null, 2));
+            return;
+        }
+        console.log(`Updated ${capability.manifest.id}. Status: ${capability.manifest.status}`);
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability trust <id>', 'Mark a capability trusted')
+    .action((id) => {
+    try {
+        const capability = updateCapabilityManifest({ id, cwd: process.cwd(), patch: { status: 'trusted' } });
+        console.log(`Trusted ${capability.manifest.id}`);
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability draft <id>', 'Mark a capability draft')
+    .action((id) => {
+    try {
+        const capability = updateCapabilityManifest({ id, cwd: process.cwd(), patch: { status: 'draft' } });
+        console.log(`Marked ${capability.manifest.id} as draft`);
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability disable <id>', 'Disable a capability')
+    .action((id) => {
+    try {
+        const capability = updateCapabilityManifest({ id, cwd: process.cwd(), patch: { status: 'disabled' } });
+        console.log(`Disabled ${capability.manifest.id}`);
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability refresh-auth <id>', 'Refresh a capability auth secret from the current browser session')
+    .option('-s, --session <id>', 'Existing Tabwright session id')
+    .option('--host <host>', 'Remote relay server host')
+    .option('--token <token>', 'Authentication token (or use TABWRIGHT_TOKEN env var)')
+    .option('--browser <headless|user|key>', 'Runtime when --session is omitted (default: user)')
+    .option('--keep-session', 'Keep auto-created session alive after refresh')
+    .option('--json', 'Print JSON envelope')
+    .option('--timeout [ms]', z.number().default(10000).describe('Execution timeout in milliseconds'))
+    .action(async (id, options) => {
+    try {
+        await refreshCapabilityAuthFromCli(id, options);
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('capability run <id>', 'Run a Tabwright capability')
+    .option('--input <json>', 'JSON input object')
+    .option('--input-json <json>', 'JSON input object')
+    .option('-s, --session <id>', 'Existing Tabwright session id')
+    .option('--host <host>', 'Remote relay server host')
+    .option('--token <token>', 'Authentication token (or use TABWRIGHT_TOKEN env var)')
+    .option('--browser <headless|user|key>', 'Runtime when --session is omitted (default: headless)')
+    .option('--force', 'Run draft capabilities or bypass URL match checks')
+    .option('--confirm <capability-id>', 'Repeat the capability id after explicit user approval of its side effect')
+    .option('--keep-session', 'Keep auto-created session alive after run')
+    .option('--json', 'Print JSON envelope')
+    .option('--timeout [ms]', z.number().default(10000).describe('Execution timeout in milliseconds'))
+    .action(async (id, options) => {
+    try {
+        await runCapabilityFromCli(id, options);
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('studio', 'Start the local Tabwright capability studio')
+    .option('--host <host>', z.string().default('127.0.0.1').describe('Host to bind to'))
+    .option('--port <port>', z.number().default(19989).describe('Port to bind to'))
+    .option('--open', 'Open the studio URL in the default browser')
+    .action(async (options) => {
+    try {
+        const { startCapabilityStudio } = await import('./capability-studio.js');
+        const server = await startCapabilityStudio({
+            host: options.host || '127.0.0.1',
+            port: options.port || 19989,
+            cwd: process.cwd(),
+        });
+        const url = `http://${server.host}:${server.port}`;
+        console.log(`Tabwright capability studio: ${url}`);
+        console.log('Press Ctrl+C to stop.');
+        if (options.open) {
+            await openInBrowser(url);
+        }
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+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 TABWRIGHT_TOKEN env var)')
+    .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.TABWRIGHT_PATCHRIGHT = '1';
+    }
+    const isLocal = !options.host && !process.env.TABWRIGHT_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('  tabwright 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: tabwright -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('  tabwright 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)
+    //   (omitted)           → undefined   (don't use direct CDP)
+    const directEndpoint = options.direct || null;
+    // If --direct with explicit endpoint, resolve it (handles host:port → ws://) then skip discovery
+    if (directEndpoint) {
+        let cdpEndpoint;
+        try {
+            cdpEndpoint = await resolveDirectInput(directEndpoint);
+        }
+        catch (error) {
+            console.error(`Error: ${error.message}`);
+            process.exit(1);
+        }
+        await ensureRelayForSessionCreation(isLocal);
+        const serverUrl = await getServerUrl(options.host);
+        const result = await createDirectSession({ serverUrl, cdpEndpoint, token: options.token });
+        console.log(`Session ${result.id} created (direct CDP). Use with: tabwright -s ${result.id} -e "..."`);
+        console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'));
+        return;
+    }
+    // If --direct with no endpoint, discover Chrome instances
+    if (options.direct === '') {
+        if (!isLocal) {
+            console.error('Error: --direct auto-discovery only works locally.');
+            console.error('For remote relay, pass an explicit endpoint reachable from the relay host:');
+            console.error('  tabwright session new --host <host> --direct ws://relay-host:9222/devtools/browser/...');
+            process.exit(1);
+        }
+        await ensureRelayForSessionCreation(isLocal);
+        console.log(pc.dim('Discovering Chrome instances with debugging enabled...'));
+        const instances = await discoverChromeInstances();
+        if (instances.length === 0) {
+            console.error('No Chrome instances with debugging enabled found.');
+            console.error('');
+            console.error('Enable debugging in one of these ways:');
+            console.error('  1. Open chrome://inspect/#remote-debugging in Chrome');
+            console.error('  2. Launch Chrome with: chrome --remote-debugging-port=9222');
+            process.exit(1);
+        }
+        if (instances.length === 1 && !options.browser) {
+            const instance = instances[0];
+            const serverUrl = await getServerUrl(options.host);
+            const result = await createDirectSession({ serverUrl, cdpEndpoint: instance.wsUrl, browser: instance.browser, profiles: instance.profiles, token: options.token });
+            const profileLabel = formatInstanceProfiles(instance);
+            console.log(`Session ${result.id} created (direct CDP, ${instance.browser}${profileLabel}). Use with: tabwright -s ${result.id} -e "..."`);
+            console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'));
+            return;
+        }
+        // Multiple instances or --browser specified
+        const directOptions = instances.map((instance) => {
+            return instanceToBrowserOption(instance);
+        });
+        if (options.browser) {
+            const selected = directOptions.find((opt) => {
+                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);
+            }
+            const serverUrl = await getServerUrl(options.host);
+            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: tabwright -s ${result.id} -e "..."`);
+            console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'));
+            return;
+        }
+        printBrowserTable(directOptions);
+        console.log('\nRun again with --browser <key>.');
+        process.exit(1);
+    }
+    // Default mode: extension-based (existing behavior)
+    let extensions = [];
+    if (isLocal) {
+        await ensureRelayServer({ logger: console });
+        extensions = await waitForConnectedExtensions({
+            timeoutMs: 12000,
+            pollIntervalMs: 250,
+            settleMs: 750,
+            logger: console,
+        });
+        if (extensions.length === 0) {
+            console.log(pc.dim('Waiting briefly for extension to reconnect...'));
+            extensions = await waitForConnectedExtensions({
+                timeoutMs: 10000,
+                pollIntervalMs: 250,
+                settleMs: 750,
+                logger: console,
+            });
+        }
+    }
+    else {
+        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: tabwright -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 Tabwright extension icon.');
+        console.error(pc.dim('Tip: Use --direct to connect via Chrome DevTools Protocol instead.'));
+        console.error(pc.dim('Tip: Run `tabwright cloud login` to use cloud browsers.'));
+        process.exit(1);
+    }
+    // Warn if any connected extension was built with an older tabwright version
+    for (const ext of extensions) {
+        const warning = getExtensionOutdatedWarning(ext.playwriterVersion);
+        if (warning) {
+            console.error(warning);
+            break;
+        }
+    }
+    // Auto-select only when the extension choice is unambiguous. With multiple
+    // profiles, a single extension with enabled tabs is the user's active choice.
+    const implicitExtension = options.browser ? null : selectImplicitExtension(extensions);
+    if (implicitExtension) {
+        const selectedExtension = implicitExtension;
+        try {
+            const serverUrl = await getServerUrl(options.host);
+            const extensionId = selectedExtension.extensionId === 'default'
+                ? null
+                : selectedExtension.stableKey || selectedExtension.extensionId;
+            const cwd = process.cwd();
+            const response = await fetch(`${serverUrl}/cli/session/new`, {
+                method: 'POST',
+                headers: buildAuthHeaders({ token: options.token, json: true }),
+                body: JSON.stringify({ extensionId, cwd }),
+            });
+            if (!response.ok) {
+                const text = await response.text();
+                console.error(`Error: ${response.status} ${text}`);
+                process.exit(1);
+            }
+            const result = (await response.json());
+            console.log(`Session ${result.id} created. Use with: tabwright -s ${result.id} -e "..."`);
+            printCloudTip();
+        }
+        catch (error) {
+            console.error(`Error: ${error.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // 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 {
+                key: ext.stableKey || ext.extensionId,
+                type: 'extension',
+                browser: ext.browser || 'Chrome',
+                profile: ext.profile?.email || '(not signed in)',
+                extensionId: ext.extensionId === 'default' ? null : ext.stableKey || ext.extensionId,
+            };
+        }),
+        ...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 === '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: tabwright -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: tabwright -s ${result.id} -e "..."`);
+                console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'));
+            }
+            else {
+                const cwd = process.cwd();
+                const response = await fetch(`${serverUrl}/cli/session/new`, {
+                    method: 'POST',
+                    headers: buildAuthHeaders({ token: options.token, json: true }),
+                    body: JSON.stringify({ extensionId: selected.extensionId, cwd }),
+                });
+                if (!response.ok) {
+                    const text = await response.text();
+                    console.error(`Error: ${response.status} ${text}`);
+                    process.exit(1);
+                }
+                const result = (await response.json());
+                console.log(`Session ${result.id} created. Use with: tabwright -s ${result.id} -e "..."`);
+                printCloudTip();
+            }
+        }
+        catch (error) {
+            console.error(`Error: ${error.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // Show unified table
+    console.log('\nMultiple browsers detected:\n');
+    printBrowserTable(allOptions);
+    console.log('\nRun again with --browser <key>.');
+    process.exit(1);
+});
+async function ensureRelayForSessionCreation(isLocal) {
+    if (isLocal) {
+        await ensureRelayServer({ logger: console });
+    }
+}
+async function createDirectSession({ serverUrl, cdpEndpoint, browser, profiles, token, }) {
+    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, profiles }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`${response.status} ${text}`);
+    }
+    return (await response.json());
+}
+function instanceToBrowserOption(instance) {
+    return {
+        key: `direct:${instance.port}`,
+        type: 'direct',
+        browser: instance.browser,
+        profile: formatInstanceProfiles(instance),
+        wsUrl: instance.wsUrl,
+        profiles: instance.profiles,
+    };
+}
+function formatInstanceProfiles(instance) {
+    if (instance.profiles.length === 0) {
+        return '(unknown)';
+    }
+    return instance.profiles
+        .map((p) => {
+        return p.email ? `${p.name} (${p.email})` : p.name;
+    })
+        .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 `tabwright cloud login` (interactive browser flow)');
+        console.error('  Option 2: Set TABWRIGHT_API_KEY env var (create one at playwriter.dev/dashboard)');
+        console.error('');
+        console.error('  Then subscribe at playwriter.dev/dashboard and run `tabwright 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 `tabwright cloud login` or set TABWRIGHT_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 `tabwright cloud subscribe` to manage your plan.');
+            console.error('  Then run `tabwright 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 `tabwright cloud login` or set TABWRIGHT_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 tabwright 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 `tabwright 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 tabwright 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 `tabwright 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) => {
+        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));
+    const browserWidth = Math.max(7, ...options.map((opt) => opt.browser.length));
+    console.log('KEY'.padEnd(keyWidth) + '  ' + 'TYPE'.padEnd(typeWidth) + '  ' + 'BROWSER'.padEnd(browserWidth) + '  ' + 'PROFILE');
+    console.log('-'.repeat(keyWidth + typeWidth + browserWidth + 20));
+    for (let i = 0; i < options.length; i++) {
+        const opt = options[i];
+        console.log(opt.key.padEnd(keyWidth) +
+            '  ' +
+            typeLabels[i].padEnd(typeWidth) +
+            '  ' +
+            opt.browser.padEnd(browserWidth) +
+            '  ' +
+            opt.profile);
+    }
+}
+cli
+    .command('doctor', 'Check Tabwright readiness and print the single best next step')
+    .option('--host <host>', 'Remote relay server host')
+    .option('--token <token>', 'Authentication token (or use TABWRIGHT_TOKEN env var)')
+    .option('--json', 'Print a machine-readable health report')
+    .action(async (options) => {
+    const isRemote = Boolean(options.host || process.env.TABWRIGHT_HOST);
+    const relayStartup = isRemote
+        ? { started: false, error: null }
+        : await ensureRelayServer({ logger: options.json ? undefined : console })
+            .then((started) => {
+            return { started: started === true, error: null };
+        })
+            .catch((error) => {
+            return {
+                started: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        });
+    const serverUrl = await getServerUrl(options.host);
+    const headers = buildAuthHeaders({ token: options.token });
+    const [relayVersion, relayFeatures, initialExtensions, sessions] = await Promise.all([
+        isRemote
+            ? fetch(`${serverUrl}/version`, { headers, signal: AbortSignal.timeout(2000) })
+                .then(async (response) => {
+                if (!response.ok) {
+                    return null;
+                }
+                const result = (await response.json());
+                return result.version || null;
+            })
+                .catch(() => {
+                return null;
+            })
+            : getRelayServerVersion(RELAY_PORT),
+        isRemote
+            ? fetch(`${serverUrl}/features`, { headers, signal: AbortSignal.timeout(2000) })
+                .then(async (response) => {
+                if (!response.ok) {
+                    return null;
+                }
+                const result = await response.json();
+                if (!result || typeof result !== 'object') {
+                    return null;
+                }
+                const features = result.features;
+                return Array.isArray(features) && features.every((feature) => typeof feature === 'string')
+                    ? features
+                    : null;
+            })
+                .catch(() => {
+                return null;
+            })
+            : getRelayServerFeatures(RELAY_PORT),
+        isRemote ? fetchExtensionsStatus({ host: options.host, token: options.token }) : getExtensionsStatus(RELAY_PORT),
+        fetch(`${serverUrl}/cli/sessions`, { headers, signal: AbortSignal.timeout(2000) })
+            .then(async (response) => {
+            if (!response.ok) {
+                return [];
+            }
+            const result = (await response.json());
+            return result.sessions || [];
+        })
+            .catch(() => {
+            return [];
+        }),
+    ]);
+    const extensions = relayStartup.started && initialExtensions.length === 0
+        ? await waitForConnectedExtensions({
+            timeoutMs: 4000,
+            pollIntervalMs: 200,
+            logger: options.json ? undefined : console,
+        })
+        : initialExtensions;
+    const report = buildDoctorReport({
+        version: VERSION,
+        cwd: process.cwd(),
+        remote: isRemote,
+        relayVersion,
+        relayFeatures,
+        relayError: relayStartup.error,
+        extensions,
+        sessions,
+        capabilityCount: listCapabilities({ cwd: process.cwd() }).length,
+        skillStatus: getTabwrightAgentSkillStatus(),
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(formatDoctorReport(report));
+});
+cli
+    .command('session list', 'List all active sessions')
+    .option('--host <host>', 'Remote relay server host')
+    .option('--token <token>', 'Authentication token (or use TABWRIGHT_TOKEN env var)')
+    .action(async (options) => {
+    if (!options.host && !process.env.TABWRIGHT_HOST) {
+        await ensureRelayServer({ logger: console });
+    }
+    const serverUrl = await getServerUrl(options.host);
+    let sessions = [];
+    try {
+        const response = await fetch(`${serverUrl}/cli/sessions`, {
+            headers: buildAuthHeaders({ token: options.token }),
+            signal: AbortSignal.timeout(2000),
+        });
+        if (!response.ok) {
+            console.error(`Error: ${response.status} ${await response.text()}`);
+            process.exit(1);
+        }
+        const result = (await response.json());
+        sessions = result.sessions;
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+    if (sessions.length === 0) {
+        console.log('No active sessions');
+        return;
+    }
+    const idWidth = Math.max(2, ...sessions.map((session) => String(session.id).length));
+    const browserWidth = Math.max(7, ...sessions.map((session) => (session.browser || 'Chrome').length));
+    const profileWidth = Math.max(7, ...sessions.map((session) => (session.profile?.email || '').length || 1));
+    const extensionWidth = Math.max(2, ...sessions.map((session) => (session.extensionId || '').length || 1));
+    const cwdWidth = Math.max(3, ...sessions.map((session) => (session.cwd || '').length || 1));
+    const stateWidth = Math.max(10, ...sessions.map((session) => session.stateKeys.join(', ').length || 1));
+    console.log('ID'.padEnd(idWidth) +
+        '  ' +
+        'BROWSER'.padEnd(browserWidth) +
+        '  ' +
+        'PROFILE'.padEnd(profileWidth) +
+        '  ' +
+        'EXT'.padEnd(extensionWidth) +
+        '  ' +
+        'CWD'.padEnd(cwdWidth) +
+        '  ' +
+        'STATE KEYS');
+    console.log('-'.repeat(idWidth + browserWidth + profileWidth + extensionWidth + cwdWidth + stateWidth + 10));
+    for (const session of sessions) {
+        const stateStr = session.stateKeys.length > 0 ? session.stateKeys.join(', ') : '-';
+        const profileLabel = session.profile?.email || '-';
+        const cwdLabel = session.cwd || '-';
+        console.log(String(session.id).padEnd(idWidth) +
+            '  ' +
+            (session.browser || 'Chrome').padEnd(browserWidth) +
+            '  ' +
+            profileLabel.padEnd(profileWidth) +
+            '  ' +
+            (session.extensionId || '-').padEnd(extensionWidth) +
+            '  ' +
+            cwdLabel.padEnd(cwdWidth) +
+            '  ' +
+            stateStr);
+    }
+});
+cli
+    .command('session delete <sessionId>', 'Delete a session and clear its state')
+    .option('--host <host>', 'Remote relay server host')
+    .option('--token <token>', 'Authentication token (or use TABWRIGHT_TOKEN env var)')
+    .action(async (sessionId, options) => {
+    const serverUrl = await getServerUrl(options.host);
+    if (!options.host && !process.env.TABWRIGHT_HOST) {
+        await ensureRelayServer({ logger: console });
+    }
+    try {
+        const response = await fetch(`${serverUrl}/cli/session/delete`, {
+            method: 'POST',
+            headers: buildAuthHeaders({ token: options.token, json: true }),
+            body: JSON.stringify({ sessionId }),
+        });
+        if (!response.ok) {
+            const result = (await response.json());
+            console.error(`Error: ${result.error}`);
+            process.exit(1);
+        }
+        console.log(`Session ${sessionId} deleted.`);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+cli
+    .command('session reset <sessionId>', 'Reset the browser connection for a session')
+    .option('--host <host>', 'Remote relay server host')
+    .option('--token <token>', 'Authentication token (or use TABWRIGHT_TOKEN env var)')
+    .action(async (sessionId, options) => {
+    const cwd = process.cwd();
+    const serverUrl = await getServerUrl(options.host);
+    if (!options.host && !process.env.TABWRIGHT_HOST) {
+        await ensureRelayServer({ logger: console });
+    }
+    try {
+        const response = await fetch(`${serverUrl}/cli/reset`, {
+            method: 'POST',
+            headers: buildAuthHeaders({ token: options.token, json: true }),
+            body: JSON.stringify({ sessionId, cwd }),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            console.error(`Error: ${response.status} ${text}`);
+            process.exit(1);
+        }
+        const result = (await response.json());
+        console.log(`Connection reset successfully. ${result.pagesCount} page(s) available. Current page URL: ${result.pageUrl}`);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+cli
+    .command('serve', `Start the relay server on this machine (must be the same host where Chrome is running). Remote clients (Docker, other machines) connect via TABWRIGHT_HOST. Use --host localhost for Docker (no token needed) — containers reach it via host.docker.internal. Use --host 0.0.0.0 for LAN/internet access (requires --token).`)
+    .option('--host [host]', z.string().default('0.0.0.0').describe('Host to bind to (use "localhost" for Docker, "0.0.0.0" for remote access)'))
+    .option('--token <token>', 'Authentication token, required when --host is 0.0.0.0 (or use TABWRIGHT_TOKEN env var)')
+    .option('--replace', 'Kill existing server if running')
+    .action(async (options) => {
+    const token = options.token || process.env.TABWRIGHT_TOKEN;
+    const isPublicHost = options.host === '0.0.0.0' || options.host === '::';
+    if (isPublicHost && !token) {
+        console.error('Error: Authentication token is required when binding to a public host.');
+        console.error('Provide --token <token> or set TABWRIGHT_TOKEN environment variable.');
+        process.exit(1);
+    }
+    // Expose the token to in-process callers so
+    // they can attach Authorization: Bearer ... when calling the relay's own
+    // privileged endpoints. Required because we no longer bypass auth for
+    // loopback — see commit history for the tunnel-agent threat model.
+    if (token) {
+        process.env.TABWRIGHT_TOKEN = token;
+    }
+    // Check if server is already running on the port
+    const net = await import('node:net');
+    const isPortInUse = await new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.setTimeout(500);
+        socket.on('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on('timeout', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.on('error', () => {
+            resolve(false);
+        });
+        socket.connect(RELAY_PORT, '127.0.0.1');
+    });
+    if (isPortInUse) {
+        if (!options.replace) {
+            console.log(`Tabwright server is already running on port ${RELAY_PORT}`);
+            console.log('Tip: Use --replace to kill the existing server and start a new one.');
+            process.exit(0);
+        }
+        // Kill existing process on the port
+        console.log(`Killing existing server on port ${RELAY_PORT}...`);
+        await killPortProcess({ port: RELAY_PORT });
+    }
+    // Lazy-load heavy dependencies only when serve command is used
+    const { createFileLogger } = await import('./create-logger.js');
+    const { startTabwrightCDPRelayServer } = await import('./cdp-relay.js');
+    const logger = createFileLogger();
+    process.title = 'tabwright-serve';
+    process.on('uncaughtException', async (err) => {
+        await logger.error('Uncaught Exception:', err);
+        process.exit(1);
+    });
+    process.on('unhandledRejection', async (reason) => {
+        await logger.error('Unhandled Rejection:', reason);
+        process.exit(1);
+    });
+    const server = await startTabwrightCDPRelayServer({
+        port: RELAY_PORT,
+        host: options.host,
+        token,
+        logger,
+    });
+    console.log('Tabwright CDP relay server started');
+    console.log(`  Host: ${options.host}`);
+    console.log(`  Port: ${RELAY_PORT}`);
+    console.log(`  Token: ${token ? '(configured)' : '(none)'}`);
+    console.log(`  Logs: ${logger.logFilePath}`);
+    console.log(`  CDP Logs: ${LOG_CDP_FILE_PATH}`);
+    console.log('');
+    console.log(`CDP endpoint: http://${options.host}:${RELAY_PORT}${token ? '?token=<token>' : ''}`);
+    console.log('');
+    console.log('Press Ctrl+C to stop.');
+    process.on('SIGINT', () => {
+        console.log('\nShutting down...');
+        server.close();
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        console.log('\nShutting down...');
+        server.close();
+        process.exit(0);
+    });
+});
+cli
+    .command('browser list', 'List all available browsers: extension-connected and direct CDP on port 9222')
+    .option('--host <host>', z.string().describe('Remote relay server host'))
+    .option('--token <token>', 'Authentication token (or use TABWRIGHT_TOKEN env var)')
+    .action(async (options) => {
+    const isLocal = !options.host && !process.env.TABWRIGHT_HOST;
+    // Start relay if local so the extension can connect, then fetch in parallel
+    if (isLocal) {
+        await ensureRelayServer({ logger: console });
+    }
+    const [extensions, directInstances] = await Promise.all([
+        isLocal
+            ? waitForConnectedExtensions({ timeoutMs: 2000, pollIntervalMs: 200, logger: console })
+            : 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 {
+                key: ext.stableKey || ext.extensionId,
+                type: 'extension',
+                browser: ext.browser || 'Chrome',
+                profile: ext.profile?.email || '(not signed in)',
+                extensionId: ext.extensionId === 'default' ? null : ext.stableKey || ext.extensionId,
+            };
+        }),
+        ...directInstances.map(instanceToBrowserOption),
+        ...headlessOption,
+        ...cloudOptions,
+    ];
+    if (allOptions.length === 0) {
+        console.log('No browsers detected.\n');
+        console.log('  Extension: click the Tabwright icon on a tab to connect');
+        console.log('  Direct:    open chrome://inspect/#remote-debugging in Chrome');
+        console.log('  Headless:  run `tabwright browser install` then `--browser headless`');
+        console.log('  Cloud:     run `tabwright cloud login` to connect cloud browsers');
+        return;
+    }
+    printBrowserTable(allOptions);
+    console.log('');
+    const hasDirectInstances = allOptions.some((opt) => {
+        return opt.type === 'direct';
+    });
+    if (hasDirectInstances) {
+        console.log(pc.dim('Connect with: tabwright session new --direct'));
+        console.log(pc.dim('Chrome may ask to approve the debugging connection.'));
+    }
+    else {
+        console.log(pc.dim('Use with: tabwright 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.TABWRIGHT_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: 'tabwright-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: 'tabwright-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 `tabwright 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 `tabwright 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 `tabwright 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: tabwright 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 `tabwright 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: tabwright 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: tabwright 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}`);
+    console.log(`cdp: ${LOG_CDP_FILE_PATH}`);
+});
+cli
+    .command('skill install', 'Install the Tabwright agent skill bundled with this CLI')
+    .option('--target <target>', 'Agent skill target (default: codex)')
+    .option('--codex-home <dir>', 'Codex home directory (defaults to CODEX_HOME or ~/.codex)')
+    .option('--force', 'Overwrite an installed Tabwright skill from another CLI build')
+    .option('--json', 'Print JSON')
+    .action((options) => {
+    try {
+        const target = parseTabwrightAgentSkillTarget(options.target);
+        const result = installTabwrightAgentSkill({
+            target,
+            codexHome: options.codexHome,
+            overwrite: options.force,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Tabwright skill ${result.fileStatus}: ${result.installedPath}`);
+        result.next.forEach((step) => {
+            console.log(`Next: ${step}`);
+        });
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli
+    .command('skill status', 'Check whether the installed Tabwright agent skill matches this CLI')
+    .option('--target <target>', 'Agent skill target (default: codex)')
+    .option('--codex-home <dir>', 'Codex home directory (defaults to CODEX_HOME or ~/.codex)')
+    .option('--json', 'Print JSON')
+    .action((options) => {
+    try {
+        const status = getTabwrightAgentSkillStatus({
+            target: parseTabwrightAgentSkillTarget(options.target),
+            codexHome: options.codexHome,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(status, null, 2));
+            return;
+        }
+        console.log(`Tabwright skill (${status.target}): ${status.state}`);
+        console.log(`Bundled: ${status.bundledPath}`);
+        console.log(`Installed: ${status.installedPath}`);
+        if (status.state !== 'current') {
+            console.log(`Next: ${status.installCommand}`);
+        }
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+cli.command('skill', 'Print the full tabwright usage instructions').action(() => {
+    const skillPath = path.join(__dirname, '..', 'src', 'skill.md');
+    const content = fs.readFileSync(skillPath, 'utf-8');
+    console.log(content);
+});
+function parseTabwrightAgentSkillTarget(value) {
+    if (!value || value === 'codex') {
+        return 'codex';
+    }
+    throw new Error(`Unsupported Tabwright skill target: ${value}. Expected codex.`);
+}
+cli.help();
+cli.completions();
+cli.version(VERSION);
+await cli.parse();
+//# sourceMappingURL=cli.js.map