@vizzly-testing/cli 0.33.0 → 0.35.0

package/dist/commands/init.js

@@ -1,20 +1,29 @@
 #!/usr/bin/env node
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { VizzlyError } from '../errors/vizzly-error.js';
 import { loadPlugins } from '../plugin-loader.js';
 import { loadConfig } from '../utils/config-loader.js';
 import * as output from '../utils/output.js';
+let commandDir = path.dirname(fileURLToPath(import.meta.url));
 let configValueSchema = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(configValueSchema), z.record(z.string(), configValueSchema)]));
 let configSchemaValidator = z.record(z.string(), configValueSchema);
 function createInitDeps(deps = {}) {
   return {
     access: deps.access || fs.access,
+    copy: deps.copy || fs.cp,
     cwd: deps.cwd || (() => process.cwd()),
+    isInteractive: deps.isInteractive || (() => Boolean(process.stdin.isTTY && process.stdout.isTTY)),
     loadConfig: deps.loadConfig || loadConfig,
     loadPlugins: deps.loadPlugins || loadPlugins,
+    mkdir: deps.mkdir || fs.mkdir,
     output: deps.output || output,
+    promptAgentSkill: deps.promptAgentSkill || promptAgentSkill,
+    readFile: deps.readFile || fs.readFile,
+    skillSourcePath: deps.skillSourcePath || getPackagedAgentSkillPath(),
     writeFile: deps.writeFile || fs.writeFile
   };
 }
@@ -28,6 +37,15 @@ function configureOutput(output, options) {
 export function getInitConfigPath(cwd = process.cwd()) {
   return path.join(cwd, 'vizzly.config.js');
 }
+export function getPackagedAgentSkillPath(baseDir = commandDir) {
+  return path.resolve(baseDir, '..', '..', 'skills', 'vizzly');
+}
+export function getProjectAgentSkillPath(cwd = process.cwd()) {
+  return path.join(cwd, '.agents', 'skills', 'vizzly');
+}
+export function getProjectAgentsPath(cwd = process.cwd()) {
+  return path.join(cwd, 'AGENTS.md');
+}
 export async function fileExists(filePath, access = fs.access) {
   try {
     await access(filePath);
@@ -162,6 +180,169 @@ function showNextSteps(output) {
   output.labelValue('Next steps', '');
   output.list(['Set your API token: export VIZZLY_TOKEN="your-api-key"', 'Run your tests with Vizzly: pnpm exec vizzly run "pnpm test"', 'Upload screenshots: pnpm exec vizzly upload ./screenshots']);
 }
+async function promptAgentSkill({
+  stdin = process.stdin,
+  stdout = process.stdout
+} = {}) {
+  let rl = createInterface({
+    input: stdin,
+    output: stdout
+  });
+  try {
+    let answer = await rl.question('Add the Vizzly agent skill to this repo? [Y/n] ');
+    return !['n', 'no'].includes(answer.trim().toLowerCase());
+  } finally {
+    rl.close();
+  }
+}
+async function shouldInstallAgentSkill(options, deps) {
+  if (options.agentGuidance) {
+    return true;
+  }
+  if (options.skipAgentSkill) {
+    return false;
+  }
+  if (options.agentSkill) {
+    return true;
+  }
+  if (options.json || !deps.isInteractive()) {
+    return false;
+  }
+  return await deps.promptAgentSkill();
+}
+let agentGuidanceStart = '<!-- vizzly-agent-guidance -->';
+let agentGuidanceEnd = '<!-- /vizzly-agent-guidance -->';
+export function createAgentGuidanceContent() {
+  return `${agentGuidanceStart}
+## Visual Testing With Vizzly
+
+Use Vizzly for user-facing UI changes when this repo has Vizzly configured.
+
+- Read visual history before changing UI: \`npx vizzly context build current --source local --agent\`
+- Inspect named screenshot history when useful: \`npx vizzly context screenshot "<screenshot-name>" --source local --json\`
+- Verify visual changes through the existing user workflow that owns the surface: \`npx vizzly tdd run "<test command>" --no-open\`
+
+Prefer existing E2E/user journeys over narrow screenshot-only specs. Treat Vizzly diffs as review evidence; do not approve or reject changes unless asked.
+${agentGuidanceEnd}
+`;
+}
+function appendSection(content, section) {
+  if (!content.trim()) {
+    return section;
+  }
+  return `${content.replace(/\s*$/, '')}\n\n${section}`;
+}
+export async function upsertProjectAgentGuidance({
+  cwd,
+  access = fs.access,
+  readFile = fs.readFile,
+  writeFile = fs.writeFile
+}) {
+  let agentsPath = getProjectAgentsPath(cwd);
+  let guidance = createAgentGuidanceContent();
+  if (!(await fileExists(agentsPath, access))) {
+    await writeFile(agentsPath, guidance, 'utf8');
+    return {
+      status: 'created',
+      agentsPath
+    };
+  }
+  let existingContent = await readFile(agentsPath, 'utf8');
+  if (existingContent.includes(agentGuidanceStart)) {
+    return {
+      status: 'exists',
+      agentsPath
+    };
+  }
+  await writeFile(agentsPath, appendSection(existingContent, guidance), 'utf8');
+  return {
+    status: 'updated',
+    agentsPath
+  };
+}
+export async function installProjectAgentSkill({
+  cwd,
+  sourcePath,
+  access = fs.access,
+  copy = fs.cp,
+  mkdir = fs.mkdir
+}) {
+  let targetPath = getProjectAgentSkillPath(cwd);
+  if (!(await fileExists(path.join(sourcePath, 'SKILL.md'), access))) {
+    return {
+      status: 'missing-source',
+      sourcePath,
+      targetPath
+    };
+  }
+  if (await fileExists(targetPath, access)) {
+    return {
+      status: 'exists',
+      sourcePath,
+      targetPath
+    };
+  }
+  await mkdir(path.dirname(targetPath), {
+    recursive: true
+  });
+  await copy(sourcePath, targetPath, {
+    recursive: true,
+    errorOnExist: true,
+    force: false
+  });
+  return {
+    status: 'installed',
+    sourcePath,
+    targetPath
+  };
+}
+function writeAgentSkillOutput(output, result) {
+  if (!result) {
+    return;
+  }
+  if (result.status === 'installed') {
+    output.complete('Added Vizzly agent skill');
+    output.hint(`Installed at ${result.targetPath}`);
+    return;
+  }
+  if (result.status === 'exists') {
+    output.hint('Vizzly agent skill already exists in this repo');
+    return;
+  }
+  if (result.status === 'missing-source') {
+    output.warn('Vizzly agent skill was not found in this CLI package');
+  }
+}
+function writeAgentGuidanceOutput(output, result) {
+  if (!result) {
+    return;
+  }
+  if (result.status === 'created') {
+    output.complete('Created AGENTS.md with Vizzly guidance');
+    output.hint(`Wrote ${result.agentsPath}`);
+    return;
+  }
+  if (result.status === 'updated') {
+    output.complete('Added Vizzly guidance to AGENTS.md');
+    output.hint(`Updated ${result.agentsPath}`);
+    return;
+  }
+  if (result.status === 'exists') {
+    output.hint('Vizzly guidance already exists in AGENTS.md');
+  }
+}
+function withAgentSetupResults(payload, {
+  agentSkillResult,
+  agentGuidanceResult
+}) {
+  if (agentSkillResult) {
+    payload.agentSkill = agentSkillResult;
+  }
+  if (agentGuidanceResult) {
+    payload.agentGuidance = agentGuidanceResult;
+  }
+  return payload;
+}
 async function writeConfigFile({
   configPath,
   plugins,
@@ -197,14 +378,37 @@ export async function init(options = {}, deps = {}) {
   let plugins = await loadInitPlugins(options, resolvedDeps);
   let configPath = getInitConfigPath(resolvedDeps.cwd());
   let hasConfig = await fileExists(configPath, resolvedDeps.access);
+  let agentSkillResult = null;
+  let agentGuidanceResult = null;
+  if (await shouldInstallAgentSkill(options, resolvedDeps)) {
+    agentSkillResult = await installProjectAgentSkill({
+      cwd: resolvedDeps.cwd(),
+      sourcePath: resolvedDeps.skillSourcePath,
+      access: resolvedDeps.access,
+      copy: resolvedDeps.copy,
+      mkdir: resolvedDeps.mkdir
+    });
+  }
+  if (options.agentGuidance) {
+    agentGuidanceResult = await upsertProjectAgentGuidance({
+      cwd: resolvedDeps.cwd(),
+      access: resolvedDeps.access,
+      readFile: resolvedDeps.readFile,
+      writeFile: resolvedDeps.writeFile
+    });
+  }
   if (hasConfig && !options.force) {
     if (options.json) {
-      resolvedDeps.output.data({
+      let payload = withAgentSetupResults({
         status: 'skipped',
         reason: 'config_exists',
         configPath,
         message: 'A vizzly.config.js file already exists. Use --force to overwrite.'
+      }, {
+        agentSkillResult,
+        agentGuidanceResult
       });
+      resolvedDeps.output.data(payload);
       return {
         status: 'skipped',
         configPath
@@ -213,6 +417,8 @@ export async function init(options = {}, deps = {}) {
     resolvedDeps.output.header('init');
     resolvedDeps.output.warn('A vizzly.config.js file already exists');
     resolvedDeps.output.hint('Use --force to overwrite');
+    writeAgentSkillOutput(resolvedDeps.output, agentSkillResult);
+    writeAgentGuidanceOutput(resolvedDeps.output, agentGuidanceResult);
     return {
       status: 'skipped',
       configPath
@@ -228,11 +434,15 @@ export async function init(options = {}, deps = {}) {
     });
     let pluginNames = getPluginConfigNames(plugins);
     if (options.json) {
-      resolvedDeps.output.data({
+      let payload = withAgentSetupResults({
         status: 'created',
         configPath,
         plugins: pluginNames
+      }, {
+        agentSkillResult,
+        agentGuidanceResult
       });
+      resolvedDeps.output.data(payload);
       return {
         status: 'created',
         configPath,
@@ -240,6 +450,8 @@ export async function init(options = {}, deps = {}) {
       };
     }
     showNextSteps(resolvedDeps.output);
+    writeAgentSkillOutput(resolvedDeps.output, agentSkillResult);
+    writeAgentGuidanceOutput(resolvedDeps.output, agentGuidanceResult);
     resolvedDeps.output.blank();
     resolvedDeps.output.complete('Vizzly CLI setup complete');
     return {

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,

package/dist/commands/upload.js

@@ -1,4 +1,5 @@
 import { createApiClient as defaultCreateApiClient, finalizeBuild as defaultFinalizeBuild, getTokenContext as defaultGetTokenContext } from '../api/index.js';
+import { CONFIG_DEFAULTS } from '../config/core.js';
 import { createUploader as defaultCreateUploader } from '../uploader/index.js';
 import { getAppBaseUrl } from '../utils/api-url.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
@@ -73,12 +74,12 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
   });
   let buildId = null;
   let config = null;
-  const uploadStartTime = Date.now();
+  let uploadStartTime = Date.now();
   try {
     output.info('Starting upload process...');
 
     // Load configuration with CLI overrides
-    const allOptions = {
+    let allOptions = {
       ...globalOptions,
       ...options
     };
@@ -95,11 +96,12 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
     }
 
     // Collect git metadata if not provided
-    const branch = await detectBranch(options.branch);
-    const commit = await detectCommit(options.commit);
-    const message = options.message || (await detectCommitMessage());
-    const buildName = await generateBuildNameWithGit(options.buildName);
-    const pullRequestNumber = detectPullRequestNumber();
+    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();
     output.info(`Uploading screenshots from: ${screenshotsPath}`);
     if (globalOptions.verbose) {
       output.info('Configuration loaded');
@@ -119,7 +121,7 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
     });
 
     // Prepare upload options with progress callback
-    const uploadOptions = {
+    let uploadOptions = {
       screenshotsDir: screenshotsPath,
       buildName,
       branch,
@@ -127,12 +129,13 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
       message,
       environment: config.build.environment,
       threshold: config.comparison.threshold,
+      minClusterSize: config.comparison.minClusterSize,
       uploadAll: options.uploadAll || false,
       metadata: options.metadata ? JSON.parse(options.metadata) : {},
       pullRequestNumber,
       parallelId: config.parallelId,
       onProgress: progressData => {
-        const {
+        let {
           message: progressMessage,
           current,
           total,
@@ -158,7 +161,7 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
 
     // Start upload
     output.progress('Starting upload...');
-    const result = await uploader.upload(uploadOptions);
+    let result = await uploader.upload(uploadOptions);
     buildId = result.buildId; // Ensure we have the buildId
 
     // Write session for subsequent commands (like preview)
@@ -263,8 +266,10 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
           executionTimeMs
         });
         output.cleanup();
+        let success = buildResult.failedComparisons === 0;
         return {
-          success: buildResult.failedComparisons === 0,
+          success,
+          exitCode: success ? 0 : 1,
           result
         };
       }
@@ -283,6 +288,14 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
       let waitBuildUrl = buildResult.url || (await buildUrlConstructor(result.buildId, config.apiUrl, config.apiKey, deps));
       output.blank();
       output.labelValue('View', output.link('Results', waitBuildUrl));
+      if (buildResult.failedComparisons > 0) {
+        output.cleanup();
+        return {
+          success: false,
+          exitCode: 1,
+          result
+        };
+      }
     }
     output.cleanup();
     return {
@@ -300,11 +313,10 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
           message: 'Vizzly API unavailable - upload skipped',
           executionTimeMs: Date.now() - uploadStartTime
         });
-        output.cleanup();
       } else {
         output.warn('Vizzly API unavailable - upload skipped. Your tests still ran.');
-        output.cleanup();
       }
+      output.cleanup();
       return {
         success: true,
         result: {
@@ -381,6 +393,12 @@ export function validateUploadOptions(screenshotsPath, options) {
       errors.push('Threshold must be a non-negative number (CIEDE2000 Delta E)');
     }
   }
+  if (options.minClusterSize !== undefined) {
+    let minClusterSize = Number(options.minClusterSize);
+    if (!Number.isInteger(minClusterSize) || minClusterSize < 1) {
+      errors.push('Min cluster size must be a positive integer');
+    }
+  }
   if (options.batchSize !== undefined) {
     let n = Number(options.batchSize);
     if (!Number.isInteger(n) || n <= 0) {