@vizzly-testing/cli 0.34.0 → 0.35.0

package/README.md

@@ -35,6 +35,9 @@ For agent-friendly repos, install the Vizzly skill and add a short project
 vizzly init --agent-guidance
 ```
 
+Use `vizzly init --agent-skill` to install only the local skill, or
+`vizzly init --skip-agent-skill` when you want config without the agent prompt.
+
 ### Start Local TDD
 
 Start the TDD server, run your tests, and open the dashboard at
@@ -54,9 +57,14 @@ Use cloud builds when you want shared baselines, team review, and CI status:
 
 ```bash
 vizzly login
+vizzly project link your-org/your-project
 vizzly run "pnpm test" --wait
 ```
 
+`vizzly login` authenticates your user account. `vizzly project link` creates a
+project-scoped upload credential for this checkout, which `vizzly run` uses for
+cloud uploads.
+
 `--wait` blocks until Vizzly finishes processing the build. It exits with code
 `1` when visual differences need review.
 
@@ -111,12 +119,23 @@ test('homepage looks correct', async ({ page }) => {
 
   let screenshot = await page.screenshot();
   await vizzlyScreenshot('homepage', screenshot, {
-    browser: 'chrome',
-    viewport: '1920x1080'
+    fullPage: true,
+    requestTimeout: 5000,
+    properties: {
+      browser: 'chrome',
+      viewport: { width: 1920, height: 1080 },
+    },
   });
 });
 ```
 
+`properties` is your metadata bag for baseline grouping, filtering, and
+debugging. SDK options such as `threshold`, `minClusterSize`, `fullPage`,
+`requestTimeout`, and `buildId` stay at the top level. If one of those reserved
+SDK options is accidentally placed inside `properties`, Vizzly removes it from
+metadata, applies it as an option when possible, and warns so the call site can
+be cleaned up.
+
 The client SDK is lightweight. It posts screenshots to the local Vizzly server
 or the cloud build wrapper. It works with any test runner.
 
@@ -136,9 +155,26 @@ await vizzlyScreenshot('homepage', './screenshots/homepage.png');
 Or upload an existing folder of screenshots:
 
 ```bash
-vizzly upload ./screenshots
+vizzly upload ./screenshots --threshold 2 --min-cluster-size 4 --batch-size 10 --upload-timeout 60000
 ```
 
+`--batch-size` controls how many screenshots are uploaded per request.
+`--upload-timeout` controls the upload client's timeout, including how long
+`--wait` polls for build processing.
+
+CI workflows can force every screenshot through even when the SHA cache says it
+already uploaded. Parallel jobs should use the same stable ID, then finalize
+that ID after every shard completes:
+
+```bash
+vizzly run "pnpm test" --upload-all --parallel-id "$GITHUB_RUN_ID"
+vizzly finalize "$GITHUB_RUN_ID"
+```
+
+For smoke jobs where cloud credentials are intentionally unavailable, add
+`--allow-no-token` to `vizzly run` and Vizzly will keep the local screenshot
+server path working without creating a cloud build.
+
 ## Configuration
 
 Generate a config file:

package/dist/api/core.js

@@ -172,7 +172,8 @@ export function buildScreenshotCheckObject(sha256, name, metadata = {}) {
     name,
     browser: meta.browser || 'chrome',
     viewport_width: meta.viewport?.width || meta.viewport_width || 1920,
-    viewport_height: meta.viewport?.height || meta.viewport_height || 1080
+    viewport_height: meta.viewport?.height || meta.viewport_height || 1080,
+    properties: meta
   };
 }
 

package/dist/cli.js

@@ -207,6 +207,7 @@ const formatHelp = (cmd, helper) => {
 };
 function extractGlobalOptionsFromArgv(argv, commandNames = null) {
   let configPath = null;
+  let tokenArg = null;
   let verboseMode = false;
   let logLevelArg = null;
   let jsonArg = null;
@@ -214,6 +215,11 @@ function extractGlobalOptionsFromArgv(argv, commandNames = null) {
     if ((argv[i] === '-c' || argv[i] === '--config') && argv[i + 1]) {
       configPath = argv[i + 1];
     }
+    if (argv[i] === '--token' && argv[i + 1]) {
+      tokenArg = argv[i + 1];
+    } else if (argv[i].startsWith('--token=')) {
+      tokenArg = argv[i].substring('--token='.length);
+    }
     if (argv[i] === '-v' || argv[i] === '--verbose') {
       verboseMode = true;
     }
@@ -234,6 +240,7 @@ function extractGlobalOptionsFromArgv(argv, commandNames = null) {
   }
   return {
     configPath,
+    tokenArg,
     verboseMode,
     logLevelArg,
     jsonArg
@@ -260,6 +267,7 @@ program.name('vizzly').description('Vizzly CLI for visual regression testing').v
 // We need to manually parse to get the config option early
 let {
   configPath,
+  tokenArg,
   verboseMode,
   logLevelArg,
   jsonArg
@@ -280,9 +288,11 @@ output.configure({
   color: colorOverride,
   json: jsonArg
 });
-const config = await loadConfig(configPath, {});
-const services = createServices(config);
-const pluginServices = createPluginServices(services);
+let config = await loadConfig(configPath, {
+  token: tokenArg
+});
+let services = createServices(config);
+let pluginServices = createPluginServices(services);
 let plugins = [];
 try {
   plugins = await loadPlugins(configPath, config);
@@ -311,8 +321,8 @@ program.command('init').description('Initialize Vizzly in your project').option(
     plugins
   });
 });
-program.command('upload').description('Upload screenshots to Vizzly').argument('<path>', 'Path to screenshots directory or file').option('-b, --build-name <name>', 'Build name for grouping').option('-m, --metadata <json>', 'Additional metadata as JSON').option('--batch-size <n>', 'Upload batch size', Number).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', Number).option('--branch <branch>', 'Git branch').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (path, options) => {
-  const globalOptions = program.opts();
+program.command('upload').description('Upload screenshots to Vizzly').argument('<path>', 'Path to screenshots directory').option('-b, --build-name <name>', 'Build name for grouping').option('-m, --metadata <json>', 'Additional metadata as JSON').option('--batch-size <n>', 'Upload batch size', Number).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', Number).option('--branch <branch>', 'Git branch').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (path, options) => {
+  let globalOptions = program.opts();
 
   // Validate options
   const validationErrors = validateUploadOptions(path, options);
@@ -323,7 +333,10 @@ program.command('upload').description('Upload screenshots to Vizzly').argument('
     }
     process.exit(1);
   }
-  await uploadCommand(path, options, globalOptions);
+  let result = await uploadCommand(path, options, globalOptions);
+  if (result?.exitCode) {
+    process.exit(result.exitCode);
+  }
 });
 
 // TDD command with subcommands - local visual review with an interactive dashboard

package/dist/client/index.js

@@ -8,22 +8,27 @@ import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { dirname, join, parse } from 'node:path';
 import { getBuildId, getServerUrl, isTddMode, setVizzlyEnabled } from '../utils/environment-config.js';
-import { createScreenshotProperties } from '../utils/screenshot-options.js';
+import { normalizeScreenshotOptions } from '../utils/screenshot-options.js';
 
 // Internal client state
 let currentClient = null;
+let currentServerUrl = null;
 let isDisabled = false;
+let currentFailOnDiff = false;
 
 // Default timeout for screenshot requests (30 seconds)
 let DEFAULT_TIMEOUT_MS = 30000;
 
 // Log levels for client SDK output control
-export let LOG_LEVELS = {
+export let LOG_LEVELS = Object.freeze({
   debug: 0,
   info: 1,
   warn: 2,
   error: 3
-};
+});
+function getEnvFailOnDiff(env = process.env) {
+  return env.VIZZLY_FAIL_ON_DIFF === 'true' || env.VIZZLY_FAIL_ON_DIFF === '1';
+}
 
 /**
  * Check if client should log at the given level
@@ -56,6 +61,7 @@ function isVizzlyDisabled() {
 function disableVizzly() {
   isDisabled = true;
   currentClient = null;
+  currentServerUrl = null;
 }
 
 /**
@@ -67,7 +73,8 @@ function disableVizzly() {
 export function autoDiscoverTddServer(startDir, deps = {}) {
   let {
     exists = existsSync,
-    readFile = readFileSync
+    readFile = readFileSync,
+    env = process.env
   } = deps;
   try {
     // Look for .vizzly/server.json in current directory and parent directories
@@ -80,6 +87,7 @@ export function autoDiscoverTddServer(startDir, deps = {}) {
           let serverInfo = JSON.parse(readFile(serverJsonPath, 'utf8'));
           if (serverInfo.port) {
             let url = `http://localhost:${serverInfo.port}`;
+            currentFailOnDiff = getEnvFailOnDiff(env) || Boolean(serverInfo.failOnDiff);
             return url;
           }
         } catch {
@@ -104,6 +112,7 @@ function getClient() {
   }
   if (!currentClient) {
     let serverUrl = getServerUrl();
+    currentFailOnDiff = getEnvFailOnDiff();
 
     // Auto-detect local TDD server and enable Vizzly if TDD server is found
     if (!serverUrl) {
@@ -116,7 +125,10 @@ function getClient() {
 
     // If we have a server URL, create the client (regardless of initial enabled state)
     if (serverUrl) {
-      currentClient = createSimpleClient(serverUrl);
+      currentServerUrl = serverUrl;
+      currentClient = createSimpleClient(serverUrl, {
+        failOnDiff: currentFailOnDiff
+      });
     }
   }
   return currentClient;
@@ -183,28 +195,38 @@ function httpPost(url, body, timeoutMs) {
  * Create a simple HTTP client for screenshots
  * @private
  */
-function createSimpleClient(serverUrl) {
+function createSimpleClient(serverUrl, clientOptions = {}) {
+  let {
+    failOnDiff = false
+  } = clientOptions;
   return {
     async screenshot(name, imageBuffer, options = {}) {
+      let normalizedOptions = normalizeScreenshotOptions(options);
+      let requestTimeout = normalizedOptions.requestTimeout || DEFAULT_TIMEOUT_MS;
+      for (let warning of normalizedOptions.warnings) {
+        console.warn(`[vizzly] ${warning.message}`);
+      }
       try {
         // If it's a string, assume it's a file path and send directly
         // Otherwise it's a Buffer, so convert to base64
         let isFilePath = typeof imageBuffer === 'string';
         let image = isFilePath ? imageBuffer : imageBuffer.toString('base64');
         let type = isFilePath ? 'file-path' : 'base64';
-        let requestTimeout = options.requestTimeout || DEFAULT_TIMEOUT_MS;
-        let properties = createScreenshotProperties(options);
+        let screenshotData = {
+          buildId: normalizedOptions.buildId ?? getBuildId(),
+          name,
+          image,
+          type,
+          properties: normalizedOptions.properties
+        };
+        if (normalizedOptions.warnings.length > 0) {
+          screenshotData.warnings = normalizedOptions.warnings;
+        }
         let httpStart = Date.now();
         let {
           status,
           json
-        } = await httpPost(`${serverUrl}/screenshot`, {
-          buildId: getBuildId(),
-          name,
-          image,
-          type,
-          properties
-        }, requestTimeout);
+        } = await httpPost(`${serverUrl}/screenshot`, screenshotData, requestTimeout);
         let httpMs = Date.now() - httpStart;
         if (shouldLogClient('debug')) {
           console.debug(`[vizzly-client] ${name} HTTP completed in ${httpMs}ms`);
@@ -215,6 +237,9 @@ function createSimpleClient(serverUrl) {
           // The summary will show all failures at the end
           if (status === 422 && json.tddMode && json.comparison) {
             let comp = json.comparison;
+            if (failOnDiff) {
+              throw new Error(`Visual diff detected for "${comp.name}" (${comp.diffPercentage ?? 0}% difference)`);
+            }
 
             // Return success so test continues and captures remaining screenshots
             // Visual diff details will be shown in the summary after tests complete
@@ -227,12 +252,15 @@ function createSimpleClient(serverUrl) {
           }
           throw new Error(`Screenshot failed: ${status} - ${json.error || 'Unknown error'}`);
         }
+        if (failOnDiff && json?.tddMode && ['diff', 'failed'].includes(json.status)) {
+          throw new Error(`Visual diff detected for "${json.name || name}" (${json.diffPercentage ?? 0}% difference)`);
+        }
         return json;
       } catch (error) {
         // Handle timeout
         if (error.message === 'Request timeout') {
           if (shouldLogClient('error')) {
-            console.error(`[vizzly] Screenshot timed out for "${name}" after ${DEFAULT_TIMEOUT_MS / 1000}s`);
+            console.error(`[vizzly] Screenshot timed out for "${name}" after ${requestTimeout / 1000}s`);
           }
           disableVizzly();
           return null;
@@ -308,7 +336,7 @@ function createSimpleClient(serverUrl) {
  * await vizzlyScreenshot('checkout-form', screenshot, {
  *   properties: {
  *     browser: 'chrome',
- *     viewport: '1920x1080'
+ *     viewport: { width: 1920, height: 1080 }
  *   },
  *   threshold: 5
  * });
@@ -366,8 +394,20 @@ export function isVizzlyReady() {
  * @param {boolean} [config.enabled] - Enable/disable screenshots
  */
 export function configure(config = {}) {
+  if ('failOnDiff' in config) {
+    currentFailOnDiff = config.failOnDiff === true;
+  } else if ('serverUrl' in config) {
+    currentFailOnDiff = getEnvFailOnDiff();
+  }
   if ('serverUrl' in config) {
-    currentClient = config.serverUrl ? createSimpleClient(config.serverUrl) : null;
+    currentServerUrl = config.serverUrl || null;
+    currentClient = config.serverUrl ? createSimpleClient(config.serverUrl, {
+      failOnDiff: currentFailOnDiff
+    }) : null;
+  } else if ('failOnDiff' in config && currentClient && currentServerUrl) {
+    currentClient = createSimpleClient(currentServerUrl, {
+      failOnDiff: currentFailOnDiff
+    });
   }
   if (typeof config.enabled === 'boolean') {
     setVizzlyEnabled(config.enabled);
@@ -397,10 +437,11 @@ export function getVizzlyInfo() {
   let client = getClient();
   return {
     enabled: !isVizzlyDisabled(),
-    serverUrl: getServerUrl(),
+    serverUrl: currentServerUrl || getServerUrl() || null,
     ready: !isVizzlyDisabled() && client !== null,
-    buildId: getBuildId(),
+    buildId: getBuildId() || null,
     tddMode: isTddMode(),
-    disabled: isVizzlyDisabled()
+    disabled: isVizzlyDisabled(),
+    failOnDiff: currentFailOnDiff
   };
 }

package/dist/commands/api.js

@@ -65,7 +65,8 @@ export function appendApiQuery(endpoint, queryOption) {
 }
 export function validateApiRequest({
   endpoint,
-  method
+  method,
+  hasData = false
 }) {
   let errors = [];
   if (method !== 'GET' && method !== 'POST') {
@@ -75,6 +76,9 @@ export function validateApiRequest({
   if (method === 'POST' && !isAllowedPostEndpoint(endpoint)) {
     errors.push(`POST not allowed for ${endpoint}. Only approve, reject, and comment endpoints support POST.`);
   }
+  if (hasData && method !== 'POST') {
+    errors.push('Request data requires --method POST.');
+  }
   return errors;
 }
 export function buildApiRequest({
@@ -85,7 +89,8 @@ export function buildApiRequest({
   let method = normalizeApiMethod(options.method || 'GET');
   let errors = validateApiRequest({
     endpoint: normalizedEndpoint,
-    method
+    method,
+    hasData: options.data !== undefined
   });
   if (errors.length > 0) {
     return {
@@ -239,7 +244,8 @@ export function validateApiOptions(endpoint, options = {}) {
   let method = normalizeApiMethod(options.method || 'GET');
   errors.push(...validateApiRequest({
     endpoint: normalizedEndpoint,
-    method
+    method,
+    hasData: options.data !== undefined
   }));
   return errors;
 }

package/dist/commands/preview.js

@@ -259,6 +259,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
     formatSessionAge = defaultFormatSessionAge,
     detectBranch = defaultDetectBranch,
     openBrowser = defaultOpenBrowser,
+    createZipWithSystem: createZip = createZipWithSystem,
     output = defaultOutput,
     exit = code => process.exit(code)
   } = deps;
@@ -284,19 +285,20 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
         reason: 'no-api-key'
       };
     }
+    let uploadPath = options.base ? resolve(path, options.base) : path;
 
     // Validate path exists and is a directory
-    if (!existsSync(path)) {
-      output.error(`Path does not exist: ${path}`);
+    if (!existsSync(uploadPath)) {
+      output.error(`Path does not exist: ${uploadPath}`);
       exit(1);
       return {
         success: false,
         reason: 'path-not-found'
       };
     }
-    let pathStat = statSync(path);
+    let pathStat = statSync(uploadPath);
     if (!pathStat.isDirectory()) {
-      output.error(`Path is not a directory: ${path}`);
+      output.error(`Path is not a directory: ${uploadPath}`);
       exit(1);
       return {
         success: false,
@@ -455,14 +457,14 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
       count: fileCount,
       totalSize,
       files
-    } = await countFiles(path, {
+    } = await countFiles(uploadPath, {
       collectPaths: options.dryRun,
       excludedDirs,
       excludedFiles
     });
     if (fileCount === 0) {
       output.stopSpinner();
-      output.error(`No files found in ${path}`);
+      output.error(`No files found in ${uploadPath}`);
       exit(1);
       return {
         success: false,
@@ -477,7 +479,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
       if (globalOptions.json) {
         output.data({
           dryRun: true,
-          path: resolve(path),
+          path: resolve(uploadPath),
           fileCount,
           totalSize,
           excludedDirs,
@@ -490,7 +492,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
       } else {
         output.info(`Dry run - would upload ${fileCount} files (${formatBytes(totalSize)})`);
         output.blank();
-        output.print(`  ${colors.brand.textTertiary('Source')}      ${resolve(path)}`);
+        output.print(`  ${colors.brand.textTertiary('Source')}      ${resolve(uploadPath)}`);
         output.print(`  ${colors.brand.textTertiary('Files')}       ${fileCount}`);
         output.print(`  ${colors.brand.textTertiary('Total size')}  ${formatBytes(totalSize)}`);
         output.blank();
@@ -538,7 +540,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
     let zipPath = join(tmpdir(), `vizzly-preview-${Date.now()}-${randomSuffix}.zip`);
     let zipBuffer;
     try {
-      await createZipWithSystem(path, zipPath, exclusions);
+      await createZip(uploadPath, zipPath, exclusions);
       zipBuffer = await readFile(zipPath);
     } catch (zipError) {
       output.stopSpinner();
@@ -569,10 +571,10 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
         success: true,
         buildId,
         previewUrl: result.previewUrl,
-        files: result.uploaded || fileCount,
+        files: result.uploaded ?? fileCount,
         bytes: totalSize,
         compressedBytes: zipBuffer.length,
-        compressionRatio,
+        compressionRatio: `${compressionPercent}%`,
         newBytes: result.newBytes,
         reusedBlobs: result.reusedBlobs || 0,
         deduplicationRatio: result.deduplicationRatio,

package/dist/commands/project.js

@@ -56,7 +56,7 @@ export async function projectLinkCommand(selector, options = {}, globalOptions =
   } = parseProjectSelector(selector, options);
   try {
     let config = await loadConfig(globalOptions.config, globalOptions);
-    let userToken = config.userToken || (await getAccessToken());
+    let userToken = config.userToken || globalOptions.token || (await getAccessToken());
     if (!userToken) {
       output.error('Login required before linking a project');
       output.hint('Run "vizzly login" first, then try project link again');

package/dist/commands/run.js

@@ -5,6 +5,7 @@
 
 import { spawn as defaultSpawn } from 'node:child_process';
 import { createBuild as defaultCreateApiBuild, createApiClient as defaultCreateApiClient, finalizeBuild as defaultFinalizeApiBuild, getBuild as defaultGetBuild, getTokenContext as defaultGetTokenContext } from '../api/index.js';
+import { CONFIG_DEFAULTS } from '../config/core.js';
 import { VizzlyError } from '../errors/vizzly-error.js';
 import { createServerManager as defaultCreateServerManager } from '../server-manager/index.js';
 import { createBuildObject as defaultCreateBuildObject } from '../services/build-manager.js';
@@ -174,10 +175,11 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
     }
 
     // Collect git metadata and build info
-    let branch = await detectBranch(options.branch);
-    let commit = await detectCommit(options.commit);
-    let message = options.message || (await detectCommitMessage());
-    let buildName = await generateBuildNameWithGit(options.buildName);
+    let configuredBuildName = config.build.name && config.build.name !== CONFIG_DEFAULTS.build.name ? config.build.name : undefined;
+    let branch = await detectBranch(options.branch || config.build.branch);
+    let commit = await detectCommit(options.commit || config.build.commit);
+    let message = options.message || config.build.message || (await detectCommitMessage());
+    let buildName = await generateBuildNameWithGit(options.buildName || configuredBuildName);
     let pullRequestNumber = detectPullRequestNumber();
     if (globalOptions.verbose) {
       output.info('Configuration loaded');
@@ -305,7 +307,7 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
       }
 
       // JSON output mode - output structured data and exit
-      if (globalOptions.json) {
+      if (globalOptions.json && !runOptions.wait) {
         let executionTimeMs = Date.now() - startTime;
         let displayUrl = await resolveBuildDisplayUrl({
           result,
@@ -490,7 +492,17 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
     // Don't fail CI for Vizzly infrastructure issues (5xx errors)
     let status = error.context?.status;
     if (status >= 500) {
-      output.warn('Vizzly API unavailable - visual tests skipped. Your tests still ran.');
+      if (globalOptions.json) {
+        output.data({
+          buildId: null,
+          status: 'skipped',
+          message: 'Vizzly API unavailable - visual tests skipped',
+          executionTimeMs: Date.now() - (startTime || Date.now())
+        });
+      } else {
+        output.warn('Vizzly API unavailable - visual tests skipped. Your tests still ran.');
+      }
+      output.cleanup();
       output.debug('api', 'API error details:', {
         error: error.message
       });

package/dist/commands/tdd-daemon.js

@@ -43,17 +43,20 @@ export function cleanupLocalDaemonFiles(directory = process.cwd(), deps = {}) {
 export function buildLegacyServerInfo({
   pid,
   port,
+  failOnDiff = false,
   now = Date.now
 }) {
   return {
     pid,
     port: port.toString(),
-    startTime: now()
+    startTime: now(),
+    failOnDiff
   };
 }
 export function writeLegacyGlobalServerFile({
   pid,
-  port
+  port,
+  failOnDiff = false
 }, {
   home = homedir,
   exists = existsSync,
@@ -71,6 +74,7 @@ export function writeLegacyGlobalServerFile({
   let serverInfo = buildLegacyServerInfo({
     pid,
     port,
+    failOnDiff,
     now
   });
   writeFile(globalServerFile, JSON.stringify(serverInfo, null, 2));
@@ -398,7 +402,8 @@ export async function tddStartCommand(options = {}, globalOptions = {}) {
     try {
       writeLegacyGlobalServerFile({
         pid: child.pid,
-        port
+        port,
+        failOnDiff: options.failOnDiff || false
       });
     } catch {
       // Non-fatal, SDK can still use health check

package/dist/commands/tdd.js

@@ -5,6 +5,7 @@
 
 import { spawn as defaultSpawn } from 'node:child_process';
 import { createBuild as defaultCreateApiBuild, createApiClient as defaultCreateApiClient, finalizeBuild as defaultFinalizeApiBuild, getBuild as defaultGetBuild } from '../api/index.js';
+import { CONFIG_DEFAULTS } from '../config/core.js';
 import { VizzlyError } from '../errors/vizzly-error.js';
 import { createServerManager as defaultCreateServerManager } from '../server-manager/index.js';
 import { createAuthService as defaultCreateAuthService } from '../services/auth-service.js';
@@ -13,7 +14,7 @@ import { createConfigService as defaultCreateConfigService } from '../services/c
 import { createProjectService as defaultCreateProjectService } from '../services/project-service.js';
 import { initializeDaemon as defaultInitializeDaemon, runTests as defaultRunTests } from '../test-runner/index.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
-import { detectBranch as defaultDetectBranch, detectCommit as defaultDetectCommit } from '../utils/git.js';
+import { detectBranch as defaultDetectBranch, detectCommit as defaultDetectCommit, detectCommitMessage as defaultDetectCommitMessage, detectPullRequestNumber as defaultDetectPullRequestNumber, generateBuildNameWithGit as defaultGenerateBuildNameWithGit } from '../utils/git.js';
 import * as defaultOutput from '../utils/output.js';
 function buildLocalContextCommand() {
   return 'vizzly context build current --source local --agent';
@@ -43,6 +44,9 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
     runTests = defaultRunTests,
     detectBranch = defaultDetectBranch,
     detectCommit = defaultDetectCommit,
+    detectCommitMessage = defaultDetectCommitMessage,
+    detectPullRequestNumber = defaultDetectPullRequestNumber,
+    generateBuildNameWithGit = defaultGenerateBuildNameWithGit,
     spawn = defaultSpawn,
     output = defaultOutput
   } = deps;
@@ -76,7 +80,7 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
     let config = await loadConfig(globalOptions.config, allOptions);
 
     // Dev mode works locally by default - only needs token for baseline download
-    let needsToken = options.baselineBuild || options.baselineComparison;
+    let needsToken = options.baselineBuild || options.baselineComparison || config.baselineBuildId || config.baselineComparisonId;
     if (!config.apiKey && needsToken) {
       throw new Error('API token required when using --baseline-build or --baseline-comparison flags');
     }
@@ -85,8 +89,12 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
     config.allowNoToken = true;
 
     // Collect git metadata
-    let branch = await detectBranch(options.branch);
-    let commit = await detectCommit(options.commit);
+    let configuredBuildName = config.build.name && config.build.name !== CONFIG_DEFAULTS.build.name ? config.build.name : undefined;
+    let branch = await detectBranch(options.branch || config.build.branch);
+    let commit = await detectCommit(options.commit || config.build.commit);
+    let message = options.message || config.build.message || (await detectCommitMessage());
+    let buildName = await generateBuildNameWithGit(options.buildName || configuredBuildName);
+    let pullRequestNumber = detectPullRequestNumber();
 
     // Show header (skip in daemon mode)
     if (!options.daemon) {
@@ -132,9 +140,21 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
       tdd: true,
       daemon: options.daemon || false,
       setBaseline: options.setBaseline || false,
+      failOnDiff: options.failOnDiff || false,
+      name: buildName,
+      buildName,
       branch,
       commit,
+      message,
       environment: config.build.environment,
+      pullRequestNumber,
+      parallelId: config.parallelId,
+      metadata: {
+        comparison: {
+          threshold: config.comparison.threshold,
+          minClusterSize: config.comparison.minClusterSize
+        }
+      },
       threshold: config.comparison.threshold,
       minClusterSize: config.comparison.minClusterSize,
       allowNoToken: config.allowNoToken || false,