screenci 0.0.54 → 0.0.56

package/dist/cli.js

@@ -1,11 +1,12 @@
 import { spawn } from 'child_process';
 import { createReadStream } from 'fs';
-import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, } from 'fs';
 import { createHash } from 'crypto';
 import { createServer } from 'http';
-import { appendFile, readdir, readFile, stat } from 'fs/promises';
+import { appendFile, readdir, readFile, stat, writeFile } from 'fs/promises';
 import { delimiter, dirname, relative as pathRelative, resolve } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
+import { confirm } from '@inquirer/prompts';
 import { Command, CommanderError } from 'commander';
 import pc from 'picocolors';
 import { logger } from './src/logger.js';
@@ -14,6 +15,8 @@ import { SCREENCI_DISABLE_RECORDING_TIMINGS_ENV, SCREENCI_MOCK_RECORD_ENV, } fro
 import { DEFAULT_RECORD_UPLOAD_POLICY } from './src/defaults.js';
 import { findDuplicateTitles, formatDuplicateTitlesMessage, } from './src/titleValidation.js';
 const SCREENCI_MOCK_RECORD_DOCS_URL = 'https://screenci.com/docs/reference/cli/#--mock-record';
+const SCREENCI_LOGIN_DOCS_URL = 'https://screenci.com/docs/reference/cli/#screenci-login';
+const SCREENCI_SECRETS_URL = 'https://app.screenci.com/secrets';
 export function collectPlaywrightListTitles(suites) {
     const titles = [];
     const visitSuite = (suite) => {
@@ -32,6 +35,9 @@ export function collectPlaywrightListTitles(suites) {
 function parsePlaywrightListReport(stdout) {
     return JSON.parse(stdout);
 }
+function logScreenCISecretGuide() {
+    logger.info(`Guide: ${pc.cyan(SCREENCI_LOGIN_DOCS_URL)}`);
+}
 async function collectDiscoveredTestTitles(configPath, additionalArgs, env) {
     const listArgs = [
         'test',
@@ -111,15 +117,19 @@ async function validateUniqueDiscoveredTestTitles(configPath, additionalArgs, en
         throw new Error(formatDuplicateTitlesMessage(duplicates));
     }
 }
-function resolveRecordingFileCandidates(filePath, configDir) {
+function resolveRecordingFileCandidates(filePath, configDir, sourceFilePath) {
+    const sourceFileCandidate = typeof sourceFilePath === 'string'
+        ? resolve(configDir, dirname(sourceFilePath), filePath)
+        : null;
     return [
         filePath,
+        ...(sourceFileCandidate ? [sourceFileCandidate] : []),
         resolve(configDir, 'videos', filePath),
         resolve(configDir, pathRelative('/app', filePath)),
     ];
 }
-async function readRecordingFile(filePath, configDir) {
-    for (const candidate of resolveRecordingFileCandidates(filePath, configDir)) {
+async function readRecordingFile(filePath, configDir, sourceFilePath) {
+    for (const candidate of resolveRecordingFileCandidates(filePath, configDir, sourceFilePath)) {
         try {
             return { buffer: await readFile(candidate), resolvedPath: candidate };
         }
@@ -144,6 +154,12 @@ function contentTypeForPath(filePath) {
     };
     return contentTypeMap[ext] ?? 'application/octet-stream';
 }
+class UploadAssetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UploadAssetError';
+    }
+}
 class UploadCancelledError extends Error {
     constructor(message = 'Upload cancelled') {
         super(message);
@@ -164,6 +180,9 @@ function isUploadCancelledError(err) {
 function isPartialUploadError(err) {
     return err instanceof PartialUploadError;
 }
+function isUploadAssetError(err) {
+    return err instanceof UploadAssetError;
+}
 function supportsInPlaceUploadUpdates(verbose) {
     return !verbose && process.stdout.isTTY === true && !process.env.CI;
 }
@@ -248,12 +267,20 @@ async function loadUploadCandidate(screenciDir, entry, verbose) {
 }
 async function uploadRecordingCandidate(candidate, screenciDir, projectName, apiUrl, secret, verbose, uploadAbort, progressReporter, progressIndex) {
     const { entry, videoName, data, preparedUploadAssets } = candidate;
+    let projectId = null;
     try {
         uploadAbort.throwIfAborted();
         const recordingPath = resolve(screenciDir, entry, 'recording.mp4');
-        const recordingHash = existsSync(recordingPath)
-            ? await hashFile(recordingPath)
-            : undefined;
+        if (!existsSync(recordingPath)) {
+            progressReporter.complete(progressIndex, 'failure');
+            return {
+                projectId: null,
+                hadFailure: true,
+                videoName,
+                failureMessage: `Missing recording.mp4 for "${videoName}"`,
+            };
+        }
+        const recordingHash = await hashFile(recordingPath);
         const startResponse = await fetch(`${apiUrl}/cli/upload/start`, {
             method: 'POST',
             headers: {
@@ -264,7 +291,7 @@ async function uploadRecordingCandidate(candidate, screenciDir, projectName, api
                 projectName,
                 videoName,
                 data,
-                ...(recordingHash !== undefined ? { recordingHash } : {}),
+                recordingHash,
                 expectedAssets: preparedUploadAssets.map((asset) => ({
                     fileHash: asset.fileHash,
                     size: asset.size,
@@ -287,53 +314,53 @@ async function uploadRecordingCandidate(candidate, screenciDir, projectName, api
                 failureMessage: formatUploadStartFailureMessage(videoName, startResponse.status, text, secret),
             };
         }
-        const { recordingId, projectId } = (await startResponse.json());
+        const startBody = (await startResponse.json());
+        const { recordingId } = startBody;
+        projectId = startBody.projectId;
         if (verbose) {
             logger.info(`recordingId=${recordingId} projectId=${projectId}`);
             logger.info(`assets=${preparedUploadAssets.length} recordingHash=${recordingHash ?? 'none'}`);
         }
         await uploadAssets(preparedUploadAssets, apiUrl, secret, recordingId, uploadAbort.signal, uploadAbort.throwIfAborted, progressReporter);
-        if (existsSync(recordingPath)) {
-            uploadAbort.throwIfAborted();
-            const fileStat = await stat(recordingPath);
-            if (verbose) {
-                logger.info(`Uploading recording.mp4 size=${(fileStat.size / 1024 / 1024).toFixed(1)}MB`);
-            }
-            const stream = createReadStream(recordingPath);
-            const abortStream = () => {
-                stream.destroy(new UploadCancelledError(`Upload cancelled for "${videoName}"`));
-            };
-            uploadAbort.signal.addEventListener('abort', abortStream, {
-                once: true,
+        uploadAbort.throwIfAborted();
+        const fileStat = await stat(recordingPath);
+        if (verbose) {
+            logger.info(`Uploading recording.mp4 size=${(fileStat.size / 1024 / 1024).toFixed(1)}MB`);
+        }
+        const stream = createReadStream(recordingPath);
+        const abortStream = () => {
+            stream.destroy(new UploadCancelledError(`Upload cancelled for "${videoName}"`));
+        };
+        uploadAbort.signal.addEventListener('abort', abortStream, {
+            once: true,
+        });
+        try {
+            const recordingResponse = await fetch(`${apiUrl}/cli/upload/${recordingId}/recording`, {
+                method: 'PUT',
+                headers: {
+                    'Content-Type': 'video/mp4',
+                    'Content-Length': String(fileStat.size),
+                    'X-ScreenCI-Secret': secret,
+                },
+                body: stream,
+                signal: uploadAbort.signal,
+                // @ts-expect-error Node.js fetch supports duplex for streaming
+                duplex: 'half',
             });
-            try {
-                const recordingResponse = await fetch(`${apiUrl}/cli/upload/${recordingId}/recording`, {
-                    method: 'PUT',
-                    headers: {
-                        'Content-Type': 'video/mp4',
-                        'Content-Length': String(fileStat.size),
-                        'X-ScreenCI-Secret': secret,
-                    },
-                    body: stream,
-                    signal: uploadAbort.signal,
-                    // @ts-expect-error Node.js fetch supports duplex for streaming
-                    duplex: 'half',
-                });
-                if (!recordingResponse.ok) {
-                    const text = await recordingResponse.text();
-                    progressReporter.complete(progressIndex, 'failure');
-                    return {
-                        projectId,
-                        hadFailure: true,
-                        videoName,
-                        failureMessage: `Failed to upload recording for "${videoName}": ${recordingResponse.status} ${text}${hint401(recordingResponse.status, secret)}`,
-                    };
-                }
-            }
-            finally {
-                uploadAbort.signal.removeEventListener('abort', abortStream);
+            if (!recordingResponse.ok) {
+                const text = await recordingResponse.text();
+                progressReporter.complete(progressIndex, 'failure');
+                return {
+                    projectId,
+                    hadFailure: true,
+                    videoName,
+                    failureMessage: `Failed to upload recording for "${videoName}": ${recordingResponse.status} ${text}${hint401(recordingResponse.status, secret)}`,
+                };
             }
         }
+        finally {
+            uploadAbort.signal.removeEventListener('abort', abortStream);
+        }
         progressReporter.complete(progressIndex, 'success');
         return { projectId, hadFailure: false, videoName };
     }
@@ -342,9 +369,18 @@ async function uploadRecordingCandidate(candidate, screenciDir, projectName, api
             progressReporter.complete(progressIndex, 'cancelled');
             throw err;
         }
+        if (isUploadAssetError(err)) {
+            progressReporter.complete(progressIndex, 'failure');
+            return {
+                projectId,
+                hadFailure: true,
+                videoName,
+                failureMessage: err instanceof Error ? err.message : String(err),
+            };
+        }
         progressReporter.complete(progressIndex, 'failure');
         return {
-            projectId: null,
+            projectId,
             hadFailure: true,
             videoName,
             failureMessage: `Network error uploading "${videoName}": ${err instanceof Error ? err.message : String(err)}`,
@@ -548,6 +584,7 @@ async function hashFile(filePath) {
     });
 }
 async function prepareCustomVoiceAssets(data, configDir) {
+    const sourceFilePath = data.metadata?.sourceFilePath;
     const customVoiceRefsByPath = new Map();
     for (const event of data.events) {
         if (event.type === 'cueStart' && event.translations) {
@@ -580,7 +617,7 @@ async function prepareCustomVoiceAssets(data, configDir) {
     }
     const preparedAssets = [];
     for (const [voicePath, refs] of customVoiceRefsByPath) {
-        const resolvedFile = await readRecordingFile(voicePath, configDir);
+        const resolvedFile = await readRecordingFile(voicePath, configDir, sourceFilePath);
         if (resolvedFile === null) {
             const existingHash = refs.find((ref) => typeof ref.assetHash === 'string')?.assetHash;
             if (!existingHash) {
@@ -615,12 +652,13 @@ async function prepareCustomVoiceAssets(data, configDir) {
     return preparedAssets;
 }
 async function collectUploadAssets(data, configDir) {
+    const sourceFilePath = data.metadata?.sourceFilePath;
     const assets = new Map();
     for (const event of data.events) {
         if (event.type === 'assetStart') {
             if (assets.has(`name:${event.name}`))
                 continue;
-            const resolvedFile = await readRecordingFile(event.path, configDir);
+            const resolvedFile = await readRecordingFile(event.path, configDir, sourceFilePath);
             if (resolvedFile === null) {
                 logger.warn(`Asset file not found, skipping upload: ${event.path}`);
                 continue;
@@ -641,7 +679,7 @@ async function collectUploadAssets(data, configDir) {
             if (typeof event.assetHash === 'string' &&
                 !assets.has(`hash:${event.assetHash}`)) {
                 const resolvedFile = typeof event.assetPath === 'string'
-                    ? await readRecordingFile(event.assetPath, configDir)
+                    ? await readRecordingFile(event.assetPath, configDir, sourceFilePath)
                     : null;
                 assets.set(`hash:${event.assetHash}`, {
                     fileHash: event.assetHash,
@@ -663,7 +701,7 @@ async function collectUploadAssets(data, configDir) {
                         !assets.has(`hash:${translation.assetHash}`)) {
                         const resolvedFile = 'assetPath' in translation &&
                             typeof translation.assetPath === 'string'
-                            ? await readRecordingFile(translation.assetPath, configDir)
+                            ? await readRecordingFile(translation.assetPath, configDir, sourceFilePath)
                             : null;
                         assets.set(`hash:${translation.assetHash}`, {
                             fileHash: translation.assetHash,
@@ -820,8 +858,7 @@ async function uploadAssets(assets, apiUrl, secret, recordingId, signal, throwIf
             });
             if (!checkRes.ok) {
                 const text = await checkRes.text();
-                logger.warn(`Failed to check asset ${asset.path}: ${checkRes.status} ${text}${hint401(checkRes.status, secret)}`);
-                continue;
+                throw new UploadAssetError(`Failed to check asset ${asset.path}: ${checkRes.status} ${text}${hint401(checkRes.status, secret)}`);
             }
             const checkBody = (await checkRes.json());
             if (checkBody.exists) {
@@ -829,8 +866,7 @@ async function uploadAssets(assets, apiUrl, secret, recordingId, signal, throwIf
                 continue;
             }
             if (!asset.fileBuffer || !asset.contentType) {
-                logger.warn(`Asset bytes not available for upload and backend does not have it yet: ${asset.path}`);
-                continue;
+                throw new UploadAssetError(`Asset bytes not available for upload and backend does not have it yet: ${asset.path}`);
             }
             throwIfAborted();
             const res = await fetch(`${apiUrl}/cli/upload/${recordingId}/asset`, {
@@ -855,7 +891,7 @@ async function uploadAssets(assets, apiUrl, secret, recordingId, signal, throwIf
                     logInfo(`Asset already exists: ${asset.path}`);
                 }
                 else {
-                    logger.warn(`Failed to upload asset ${asset.path}: ${res.status} ${text}${hint401(res.status, secret)}`);
+                    throw new UploadAssetError(`Failed to upload asset ${asset.path}: ${res.status} ${text}${hint401(res.status, secret)}`);
                 }
             }
             else {
@@ -866,7 +902,10 @@ async function uploadAssets(assets, apiUrl, secret, recordingId, signal, throwIf
             if (isUploadCancelledError(err)) {
                 throw err;
             }
-            logger.warn(`Network error uploading asset ${asset.path}:`, err);
+            if (isUploadAssetError(err)) {
+                throw err;
+            }
+            throw new UploadAssetError(`Network error uploading asset ${asset.path}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 }
@@ -971,14 +1010,21 @@ async function loadScreenCIConfigAndEnv(configPath) {
         process.exit(1);
     }
     if (screenciConfig.envFile) {
-        const envFilePath = resolve(dirname(resolvedConfigPath), screenciConfig.envFile);
-        loadEnvFile(envFilePath, true);
+        loadEnvFile(resolve(dirname(resolvedConfigPath), screenciConfig.envFile), true);
+    }
+    else {
+        loadEnvFile(resolve(dirname(resolvedConfigPath), '.env'), false);
     }
     return { resolvedConfigPath, screenciConfig };
 }
 function loadEnvFile(envFilePath, warnOnFailure) {
     try {
-        process.loadEnvFile(envFilePath);
+        const loadEnvFileCompat = process.loadEnvFile;
+        if (typeof loadEnvFileCompat === 'function') {
+            loadEnvFileCompat(envFilePath);
+            return;
+        }
+        loadEnvFileFallback(envFilePath);
     }
     catch (err) {
         if (warnOnFailure && !isMissingFileError(err)) {
@@ -986,6 +1032,58 @@ function loadEnvFile(envFilePath, warnOnFailure) {
         }
     }
 }
+function loadEnvFileFallback(envFilePath) {
+    const envSource = readFileSync(envFilePath, 'utf8');
+    for (const [key, value] of parseEnvFile(envSource)) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+}
+function parseEnvFile(envSource) {
+    const parsed = new Map();
+    const lines = envSource.replace(/^\uFEFF/, '').split(/\r?\n/);
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const normalizedLine = line.startsWith('export ')
+            ? line.slice('export '.length).trimStart()
+            : line;
+        const separatorIndex = normalizedLine.indexOf('=');
+        if (separatorIndex === -1)
+            continue;
+        const key = normalizedLine.slice(0, separatorIndex).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        const rawValue = normalizedLine.slice(separatorIndex + 1).trim();
+        parsed.set(key, parseEnvValue(rawValue));
+    }
+    return parsed;
+}
+function parseEnvValue(rawValue) {
+    if (rawValue === '')
+        return '';
+    if ((rawValue.startsWith('"') && rawValue.endsWith('"')) ||
+        (rawValue.startsWith("'") && rawValue.endsWith("'"))) {
+        const quote = rawValue[0];
+        const quotedValue = rawValue.slice(1, -1);
+        if (quote === '"') {
+            return quotedValue
+                .replace(/\\n/g, '\n')
+                .replace(/\\r/g, '\r')
+                .replace(/\\t/g, '\t')
+                .replace(/\\"/g, '"')
+                .replace(/\\\\/g, '\\');
+        }
+        return quotedValue;
+    }
+    const inlineCommentIndex = rawValue.search(/\s#/);
+    if (inlineCommentIndex >= 0) {
+        return rawValue.slice(0, inlineCommentIndex).trimEnd();
+    }
+    return rawValue;
+}
 function isMissingFileError(err) {
     return (typeof err === 'object' &&
         err !== null &&
@@ -995,10 +1093,9 @@ function isMissingFileError(err) {
 async function loadEnvFileFromConfigSource(resolvedConfigPath, warnOnFailure) {
     try {
         const screenciConfig = await tryReadConfigFromSource(resolvedConfigPath);
-        if (screenciConfig.envFile) {
-            const envFilePath = resolve(dirname(resolvedConfigPath), screenciConfig.envFile);
-            loadEnvFile(envFilePath, warnOnFailure);
-        }
+        loadEnvFile(screenciConfig.envFile
+            ? resolve(dirname(resolvedConfigPath), screenciConfig.envFile)
+            : resolve(dirname(resolvedConfigPath), '.env'), warnOnFailure);
     }
     catch {
         // Config import may require Playwright context or dynamic values. Continue with
@@ -1016,6 +1113,10 @@ async function resolveConfiguredEnvFilePath(resolvedConfigPath) {
         return undefined;
     }
 }
+async function resolveProjectEnvFilePath(resolvedConfigPath) {
+    return ((await resolveConfiguredEnvFilePath(resolvedConfigPath)) ??
+        resolve(dirname(resolvedConfigPath), '.env'));
+}
 export function extractConfigStringLiteral(configSource, property) {
     const singleQuoteMatch = configSource.match(new RegExp(property + "\\s*:\\s*'([^'\\n]+)'"));
     if (singleQuoteMatch)
@@ -1094,7 +1195,9 @@ async function requireScreenCISecret(configPath) {
     const { resolvedConfigPath, screenciConfig } = await loadScreenCIConfigAndEnv(configPath);
     const secret = process.env.SCREENCI_SECRET;
     if (!secret) {
-        logger.error('No secret configured. Set SCREENCI_SECRET in your .env file (get it from the API Key page in the dashboard).');
+        const envFilePath = await resolveProjectEnvFilePath(resolvedConfigPath);
+        logger.error(`No SCREENCI_SECRET configured. Run ${pc.cyan('screenci login')} or add SCREENCI_SECRET to ${envFilePath}. You can get the secret manually from ${SCREENCI_SECRETS_URL}.`);
+        logScreenCISecretGuide();
         process.exit(1);
     }
     return {
@@ -1155,8 +1258,47 @@ function openBrowser(url) {
         logger.warn('Failed to open browser automatically:', err);
     }
 }
-async function performBrowserLogin(appUrl) {
+async function promptToOpenLoginUrl() {
+    return await confirm({
+        message: 'Open this link in your browser now?',
+        default: false,
+    });
+}
+async function persistScreenCISecret(envFilePath, secret) {
+    const nextLine = `SCREENCI_SECRET=${secret}`;
+    try {
+        const existing = await readFile(envFilePath, 'utf-8');
+        const lines = existing === '' ? [] : existing.split(/\r?\n/);
+        const firstSecretIndex = lines.findIndex((line) => line.startsWith('SCREENCI_SECRET='));
+        const linesWithoutSecret = lines.filter((line) => !line.startsWith('SCREENCI_SECRET='));
+        const finalLines = firstSecretIndex >= 0
+            ? [
+                ...linesWithoutSecret.slice(0, firstSecretIndex),
+                nextLine,
+                ...linesWithoutSecret.slice(firstSecretIndex),
+            ]
+            : [...linesWithoutSecret, nextLine];
+        let nextContent = finalLines.join('\n');
+        if (!nextContent.endsWith('\n'))
+            nextContent += '\n';
+        await writeFile(envFilePath, nextContent);
+        return;
+    }
+    catch (err) {
+        if (!isMissingFileError(err))
+            throw err;
+    }
+    await writeFile(envFilePath, `${nextLine}\n`);
+}
+async function performBrowserLogin(appUrl, options) {
     return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            callback();
+        };
         const server = createServer((req, res) => {
             try {
                 const reqUrl = new URL(req.url ?? '/', 'http://localhost');
@@ -1165,34 +1307,48 @@ async function performBrowserLogin(appUrl) {
                     res.writeHead(200, { 'Content-Type': 'text/html' });
                     res.end('<html><body style="font-family:sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0"><p style="font-size:1.2rem">Setup complete! You can close this tab.</p></body></html>');
                     server.close();
-                    resolve(secret);
+                    finish(() => resolve(secret));
                 }
                 else {
                     res.writeHead(400, { 'Content-Type': 'text/html' });
                     res.end('<html><body style="font-family:sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0"><p style="color:red;font-size:1.2rem">Authentication failed: no secret received. Please try again.</p></body></html>');
                     server.close();
-                    reject(new Error('No secret received in callback'));
+                    finish(() => reject(new Error('No secret received in callback')));
                 }
             }
             catch (err) {
                 res.writeHead(500);
                 res.end('Internal error');
                 server.close();
-                reject(err);
+                finish(() => reject(err));
             }
         });
         server.listen(0, '127.0.0.1', () => {
             const port = server.address().port;
             const callbackUrl = `http://localhost:${port}/callback`;
             const loginUrl = `${appUrl}/cli-auth?callback=${encodeURIComponent(callbackUrl)}`;
-            logger.info(`If the browser does not open automatically, visit:`);
+            logger.info('Open this link to log in to ScreenCI:');
             logger.info(pc.cyan(loginUrl));
             logger.info('');
-            openBrowser(loginUrl);
+            void (async () => {
+                if (options?.openBrowserImmediately) {
+                    openBrowser(loginUrl);
+                    return;
+                }
+                const shouldOpen = await promptToOpenLoginUrl();
+                if (shouldOpen) {
+                    openBrowser(loginUrl);
+                    return;
+                }
+                logger.info('Browser not opened. Keep this command running and open the link manually to continue.');
+            })().catch((err) => {
+                server.close();
+                finish(() => reject(err));
+            });
         });
         const timeout = setTimeout(() => {
             server.close();
-            reject(new Error('Authentication timed out after 5 minutes'));
+            finish(() => reject(new Error('Authentication timed out after 15 minutes')));
         }, 15 * 60 * 1000);
         server.on('close', () => clearTimeout(timeout));
     });
@@ -1201,36 +1357,68 @@ export async function ensureScreenciSecret(resolvedConfigPath) {
     const existingSecret = process.env.SCREENCI_SECRET;
     if (existingSecret)
         return existingSecret;
-    logger.info('Opening browser for authentication to get your SCREENCI_SECRET...');
     const appUrl = getDevFrontendUrl();
     try {
-        const secret = await performBrowserLogin(appUrl);
+        const secret = await performBrowserLogin(appUrl, {
+            openBrowserImmediately: true,
+        });
         process.env.SCREENCI_SECRET = secret;
         const savePath = resolvedConfigPath
-            ? ((await resolveConfiguredEnvFilePath(resolvedConfigPath)) ??
-                resolve(process.cwd(), '.env'))
+            ? await resolveProjectEnvFilePath(resolvedConfigPath)
             : resolve(process.cwd(), '.env');
-        await appendFile(savePath, `SCREENCI_SECRET=${secret}\n`);
+        await persistScreenCISecret(savePath, secret);
         logger.info(`Successfully saved SCREENCI_SECRET to ${savePath}`);
         return secret;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         logger.warn(`Authentication failed: ${msg}`);
-        logger.info('You can add SCREENCI_SECRET manually to .env later (get it from the API Key page in the dashboard).');
+        logger.info(`You can add SCREENCI_SECRET manually to .env later. Get it from ${SCREENCI_SECRETS_URL}.`);
+        logScreenCISecretGuide();
         return undefined;
     }
 }
+async function runLogin(configPath, open = false) {
+    const { resolvedConfigPath } = await loadScreenCIConfigAndEnv(configPath);
+    if (process.env.SCREENCI_SECRET) {
+        logger.info('SCREENCI_SECRET is already configured.');
+        return;
+    }
+    const savePath = await resolveProjectEnvFilePath(resolvedConfigPath);
+    const appUrl = getDevFrontendUrl();
+    try {
+        const secret = await performBrowserLogin(appUrl, {
+            openBrowserImmediately: open,
+        });
+        process.env.SCREENCI_SECRET = secret;
+        await persistScreenCISecret(savePath, secret);
+        logger.info(`Successfully saved SCREENCI_SECRET to ${savePath}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`Authentication failed: ${msg}`);
+        logger.info(`You can run ${pc.cyan('screenci login')} again or add SCREENCI_SECRET manually to ${savePath}. Get it from ${SCREENCI_SECRETS_URL}.`);
+        logScreenCISecretGuide();
+    }
+}
 export async function main() {
     if (process.argv.length <= 2) {
         logger.error('Error: No command provided');
-        logger.error('Available commands: record, test, info, make-public, make-private, init');
+        logger.error('Available commands: login, record, test, info, make-public, make-private, init');
         process.exit(1);
     }
     const program = new Command();
     const defaultPackageManager = determinePackageManager();
     program.name('screenci');
     program.exitOverride();
+    program
+        .command('login')
+        .description('Authenticate and save SCREENCI_SECRET for this project')
+        .option('-c, --config <path>', 'path to screenci.config.ts')
+        .option('--open', 'open the login URL in your browser immediately')
+        .action(async (options) => {
+        await runLogin(options.config, options.open === true);
+    });
     // record command — playwright args pass through as-is
     program
         .command('record [playwrightArgs...]')
@@ -1260,10 +1448,9 @@ export async function main() {
         if (resolvedConfigPath) {
             try {
                 const screenciConfig = await loadRecordConfigWithoutPlaywrightCollision(resolvedConfigPath);
-                if (screenciConfig.envFile) {
-                    const envFilePath = resolve(dirname(resolvedConfigPath), screenciConfig.envFile);
-                    loadEnvFile(envFilePath, true);
-                }
+                loadEnvFile(screenciConfig.envFile
+                    ? resolve(dirname(resolvedConfigPath), screenciConfig.envFile)
+                    : resolve(dirname(resolvedConfigPath), '.env'), true);
                 const apiUrl = getDevBackendUrl();
                 const appUrl = getDevFrontendUrl();
                 const secret = process.env.SCREENCI_SECRET;
@@ -1275,7 +1462,7 @@ export async function main() {
                     logger.info('All recordings failed.');
                 }
                 else if (!secret) {
-                    logger.info('No secret configured, skipping upload. Set SCREENCI_SECRET in your .env file.');
+                    logger.info('No SCREENCI_SECRET configured for uploads. Run screenci login or add it to the project env file.');
                 }
                 else if (playwrightFailure !== null &&
                     uploadPolicy === 'all-or-nothing') {
@@ -1530,7 +1717,9 @@ async function run(command, additionalArgs, customConfigPath, verbose = false, m
     }
     // Only validate args for record command
     if (command === 'record') {
-        await ensureScreenciSecret(configPath);
+        if (!process.env.SCREENCI_SECRET) {
+            await requireScreenCISecret(configPath);
+        }
         validateArgs(additionalArgs);
         const screenciDir = resolve(dirname(configPath), '.screenci');
         clearDirectory(screenciDir);
@@ -1538,6 +1727,7 @@ async function run(command, additionalArgs, customConfigPath, verbose = false, m
     const envForChild = { ...process.env };
     await validateUniqueDiscoveredTestTitles(configPath, additionalArgs, {
         ...envForChild,
+        SCREENCI_CONFIG_DIR: dirname(configPath),
         ...(command === 'record' ? { SCREENCI_RECORDING: 'true' } : {}),
         ...(command === 'test' && !mockRecord
             ? { [SCREENCI_DISABLE_RECORDING_TIMINGS_ENV]: 'true' }
@@ -1562,6 +1752,7 @@ async function run(command, additionalArgs, customConfigPath, verbose = false, m
             : {}),
         env: {
             ...envForChild,
+            SCREENCI_CONFIG_DIR: dirname(configPath),
             // Enable recording only for record command
             ...(command === 'record' ? { SCREENCI_RECORDING: 'true' } : {}),
             ...(command === 'test' && !mockRecord