@vizzly-testing/cli 0.6.0 → 0.7.1

package/README.md

@@ -82,6 +82,7 @@ await vizzlyScreenshot('homepage', screenshot, {
 vizzly upload <directory>           # Upload screenshots from directory
 vizzly upload ./screenshots --wait  # Wait for processing
 vizzly upload ./screenshots --upload-all  # Upload all without deduplication
+vizzly upload ./screenshots --parallel-id "ci-run-123"  # For parallel CI builds
 ```
 
 ### Run Tests with Integration
@@ -90,6 +91,7 @@ vizzly run "npm test"               # Run with Vizzly integration
 vizzly run "pytest" --port 3002     # Custom port
 vizzly run "npm test" --wait        # Wait for build completion
 vizzly run "npm test" --allow-no-token  # Run without API token
+vizzly run "npm test" --parallel-id "ci-run-123"  # For parallel CI builds
 ```
 
 #### Run Command Options
@@ -111,6 +113,9 @@ vizzly run "npm test" --allow-no-token  # Run without API token
 - `--upload-timeout <ms>` - Upload wait timeout in ms
 - `--upload-all` - Upload all screenshots without SHA deduplication
 
+**Parallel Execution:**
+- `--parallel-id <id>` - Unique identifier for parallel test execution (also via `VIZZLY_PARALLEL_ID`)
+
 **Development & Testing:**
 - `--allow-no-token` - Allow running without API token (useful for local development)
 - `--token <token>` - API token override
@@ -150,6 +155,7 @@ vizzly init                         # Create vizzly.config.js with defaults
 vizzly status <build-id>            # Check build progress and results
 vizzly status <build-id> --verbose  # Detailed build information
 vizzly status <build-id> --json     # Machine-readable output
+vizzly finalize <parallel-id>       # Finalize parallel build after all shards complete
 vizzly doctor                       # Fast local preflight (no network)
 vizzly doctor --api                 # Include API connectivity checks
 ```
@@ -289,6 +295,37 @@ For CI/CD pipelines, use the `--wait` flag to wait for visual comparison results
     VIZZLY_BRANCH: ${{ github.head_ref || github.ref_name }}
 ```
 
+### Parallel Builds in CI
+
+For parallel test execution, use `--parallel-id` to ensure all shards contribute to the same build:
+
+```yaml
+# GitHub Actions with parallel matrix
+jobs:
+  e2e-tests:
+    strategy:
+      matrix:
+        shard: [1/4, 2/4, 3/4, 4/4]
+    steps:
+      - name: Run tests with Vizzly
+        run: |
+          npx vizzly run "npm test -- --shard=${{ matrix.shard }}" \
+            --parallel-id="${{ github.run_id }}-${{ github.run_attempt }}"
+        env:
+          VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
+
+  finalize-e2e:
+    needs: e2e-tests
+    runs-on: ubuntu-latest
+    if: always() && needs.e2e-tests.result == 'success'
+    steps:
+      - name: Finalize parallel build
+        run: |
+          npx vizzly finalize "${{ github.run_id }}-${{ github.run_attempt }}"
+        env:
+          VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
+```
+
 ### GitLab CI
 ```yaml
 visual-tests:
@@ -334,6 +371,9 @@ Check if Vizzly is enabled in the current environment.
 - `VIZZLY_API_URL`: Override API base URL. Default: `https://vizzly.dev`.
 - `VIZZLY_LOG_LEVEL`: Logger level. One of `debug`, `info`, `warn`, `error`. Example: `export VIZZLY_LOG_LEVEL=debug`.
 
+### Parallel Builds
+- `VIZZLY_PARALLEL_ID`: Unique identifier for parallel test execution. Example: `export VIZZLY_PARALLEL_ID=ci-run-123`.
+
 ### Git Information Override
 For enhanced CI/CD integration, you can override git detection with these environment variables:
 

package/dist/cli.js

@@ -6,6 +6,7 @@ import { uploadCommand, validateUploadOptions } from './commands/upload.js';
 import { runCommand, validateRunOptions } from './commands/run.js';
 import { tddCommand, validateTddOptions } from './commands/tdd.js';
 import { statusCommand, validateStatusOptions } from './commands/status.js';
+import { finalizeCommand, validateFinalizeOptions } from './commands/finalize.js';
 import { doctorCommand, validateDoctorOptions } from './commands/doctor.js';
 import { getPackageVersion } from './utils/package-info.js';
 program.name('vizzly').description('Vizzly CLI for visual regression testing').version(getPackageVersion()).option('-c, --config <path>', 'Config file path').option('--token <token>', 'Vizzly API token').option('-v, --verbose', 'Verbose output').option('--json', 'Machine-readable output').option('--no-color', 'Disable colored output');
@@ -16,7 +17,7 @@ program.command('init').description('Initialize Vizzly in your project').option(
     ...options
   });
 });
-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', v => parseInt(v, 10)).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', v => parseInt(v, 10)).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', parseFloat).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--upload-all', 'Upload all screenshots without SHA deduplication').action(async (path, options) => {
+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', v => parseInt(v, 10)).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', v => parseInt(v, 10)).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', parseFloat).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();
 
   // Validate options
@@ -59,7 +60,7 @@ program.command('tdd').description('Run tests in TDD mode with local visual comp
   }
   await cleanup();
 });
-program.command('run').description('Run tests with Vizzly integration').argument('<command>', 'Test command to run').option('--port <port>', 'Port for screenshot server', '47392').option('-b, --build-name <name>', 'Custom build name').option('--branch <branch>', 'Git branch override').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--allow-no-token', 'Allow running without API token').option('--upload-all', 'Upload all screenshots without SHA deduplication').action(async (command, options) => {
+program.command('run').description('Run tests with Vizzly integration').argument('<command>', 'Test command to run').option('--port <port>', 'Port for screenshot server', '47392').option('-b, --build-name <name>', 'Custom build name').option('--branch <branch>', 'Git branch override').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--allow-no-token', 'Allow running without API token').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (command, options) => {
   const globalOptions = program.opts();
 
   // Validate options
@@ -94,6 +95,18 @@ program.command('status').description('Check the status of a build').argument('<
   }
   await statusCommand(buildId, options, globalOptions);
 });
+program.command('finalize').description('Finalize a parallel build after all shards complete').argument('<parallel-id>', 'Parallel ID to finalize').action(async (parallelId, options) => {
+  const globalOptions = program.opts();
+
+  // Validate options
+  const validationErrors = validateFinalizeOptions(parallelId, options);
+  if (validationErrors.length > 0) {
+    console.error('Validation errors:');
+    validationErrors.forEach(error => console.error(`  - ${error}`));
+    process.exit(1);
+  }
+  await finalizeCommand(parallelId, options, globalOptions);
+});
 program.command('doctor').description('Run diagnostics to check your environment and configuration').option('--api', 'Include API connectivity checks').action(async options => {
   const globalOptions = program.opts();
 

package/dist/commands/finalize.js

@@ -0,0 +1,72 @@
+import { loadConfig } from '../utils/config-loader.js';
+import { ConsoleUI } from '../utils/console-ui.js';
+import { createServiceContainer } from '../container/index.js';
+
+/**
+ * Finalize command implementation
+ * @param {string} parallelId - Parallel ID to finalize
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function finalizeCommand(parallelId, options = {}, globalOptions = {}) {
+  // Create UI handler
+  const ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    // Load configuration with CLI overrides
+    const allOptions = {
+      ...globalOptions,
+      ...options
+    };
+    const config = await loadConfig(globalOptions.config, allOptions);
+
+    // Validate API token
+    if (!config.apiKey) {
+      ui.error('API token required. Use --token or set VIZZLY_TOKEN environment variable');
+      return;
+    }
+    if (globalOptions.verbose) {
+      ui.info('Configuration loaded', {
+        parallelId,
+        apiUrl: config.apiUrl
+      });
+    }
+
+    // Create service container and get API service
+    ui.startSpinner('Finalizing parallel build...');
+    const container = await createServiceContainer(config, 'finalize');
+    const apiService = await container.get('apiService');
+    ui.stopSpinner();
+
+    // Call finalize endpoint
+    const result = await apiService.finalizeParallelBuild(parallelId);
+    if (globalOptions.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      ui.success(`Parallel build ${result.build.id} finalized successfully`);
+      ui.info(`Status: ${result.build.status}`);
+      ui.info(`Parallel ID: ${result.build.parallel_id}`);
+    }
+  } catch (error) {
+    ui.stopSpinner();
+    ui.error('Failed to finalize parallel build', error);
+  } finally {
+    ui.cleanup();
+  }
+}
+
+/**
+ * Validate finalize options
+ * @param {string} parallelId - Parallel ID to finalize
+ * @param {Object} options - Command options
+ */
+export function validateFinalizeOptions(parallelId, _options) {
+  const errors = [];
+  if (!parallelId || parallelId.trim() === '') {
+    errors.push('Parallel ID is required');
+  }
+  return errors;
+}

package/dist/commands/run.js

@@ -162,7 +162,8 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
       allowNoToken: config.allowNoToken || false,
       wait: config.wait || options.wait || false,
       uploadAll: options.uploadAll || false,
-      pullRequestNumber
+      pullRequestNumber,
+      parallelId: config.parallelId
     };
 
     // Start test run

package/dist/commands/upload.js

@@ -101,6 +101,7 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
       uploadAll: options.uploadAll || false,
       metadata: options.metadata ? JSON.parse(options.metadata) : {},
       pullRequestNumber,
+      parallelId: config.parallelId,
       onProgress: progressData => {
         const {
           message: progressMessage,

package/dist/services/api-service.js

@@ -241,4 +241,18 @@ export class ApiService {
   async getTokenContext() {
     return this.request('/api/sdk/token/context');
   }
+
+  /**
+   * Finalize a parallel build
+   * @param {string} parallelId - Parallel ID to finalize
+   * @returns {Promise<Object>} Finalization result
+   */
+  async finalizeParallelBuild(parallelId) {
+    return this.request(`/api/sdk/parallel/${parallelId}/finalize`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    });
+  }
 }

package/dist/services/tdd-service.js

@@ -159,9 +159,15 @@ export class TddService {
         });
       }
 
-      // Download each screenshot (with efficient SHA checking)
+      // Download screenshots in batches with progress indication
       let downloadedCount = 0;
       let skippedCount = 0;
+      let errorCount = 0;
+      const totalScreenshots = buildDetails.screenshots.length;
+      const batchSize = 5; // Download up to 5 screenshots concurrently
+
+      // Filter screenshots that need to be downloaded
+      const screenshotsToProcess = [];
       for (const screenshot of buildDetails.screenshots) {
         // Sanitize screenshot name for security
         let sanitizedName;
@@ -169,6 +175,7 @@ export class TddService {
           sanitizedName = sanitizeScreenshotName(screenshot.name);
         } catch (error) {
           logger.warn(`Skipping screenshot with invalid name '${screenshot.name}': ${error.message}`);
+          errorCount++;
           continue;
         }
         const imagePath = safePath(this.baselinePath, `${sanitizedName}.png`);
@@ -190,28 +197,75 @@ export class TddService {
         const downloadUrl = screenshot.original_url || screenshot.url;
         if (!downloadUrl) {
           logger.warn(`⚠️  Screenshot ${sanitizedName} has no download URL - skipping`);
-          continue; // Skip screenshots without URLs
+          errorCount++;
+          continue;
         }
-        logger.debug(`📥 Downloading screenshot: ${sanitizedName} from ${downloadUrl}`);
-        try {
-          // Download the image
-          const response = await fetchWithTimeout(downloadUrl);
-          if (!response.ok) {
-            throw new NetworkError(`Failed to download ${sanitizedName}: ${response.statusText}`);
-          }
-          const arrayBuffer = await response.arrayBuffer();
-          const imageBuffer = Buffer.from(arrayBuffer);
-          writeFileSync(imagePath, imageBuffer);
-          downloadedCount++;
-          logger.debug(`✓ Downloaded ${sanitizedName}.png`);
-        } catch (error) {
-          logger.warn(`⚠️  Failed to download ${sanitizedName}: ${error.message}`);
+        screenshotsToProcess.push({
+          screenshot,
+          sanitizedName,
+          imagePath,
+          downloadUrl
+        });
+      }
+
+      // Process downloads in batches
+      const actualDownloadsNeeded = screenshotsToProcess.length;
+      if (actualDownloadsNeeded > 0) {
+        logger.info(`📥 Downloading ${actualDownloadsNeeded} new/updated screenshots in batches of ${batchSize}...`);
+        for (let i = 0; i < screenshotsToProcess.length; i += batchSize) {
+          const batch = screenshotsToProcess.slice(i, i + batchSize);
+          const batchNum = Math.floor(i / batchSize) + 1;
+          const totalBatches = Math.ceil(screenshotsToProcess.length / batchSize);
+          logger.info(`📦 Processing batch ${batchNum}/${totalBatches} (${batch.length} screenshots)`);
+
+          // Download batch concurrently
+          const downloadPromises = batch.map(async ({
+            sanitizedName,
+            imagePath,
+            downloadUrl
+          }) => {
+            try {
+              logger.debug(`📥 Downloading: ${sanitizedName}`);
+              const response = await fetchWithTimeout(downloadUrl);
+              if (!response.ok) {
+                throw new NetworkError(`Failed to download ${sanitizedName}: ${response.statusText}`);
+              }
+              const arrayBuffer = await response.arrayBuffer();
+              const imageBuffer = Buffer.from(arrayBuffer);
+              writeFileSync(imagePath, imageBuffer);
+              logger.debug(`✓ Downloaded ${sanitizedName}.png`);
+              return {
+                success: true,
+                name: sanitizedName
+              };
+            } catch (error) {
+              logger.warn(`⚠️  Failed to download ${sanitizedName}: ${error.message}`);
+              return {
+                success: false,
+                name: sanitizedName,
+                error: error.message
+              };
+            }
+          });
+          const batchResults = await Promise.all(downloadPromises);
+          const batchSuccesses = batchResults.filter(r => r.success).length;
+          const batchFailures = batchResults.filter(r => !r.success).length;
+          downloadedCount += batchSuccesses;
+          errorCount += batchFailures;
+
+          // Show progress
+          const totalProcessed = downloadedCount + skippedCount + errorCount;
+          const progressPercent = Math.round(totalProcessed / totalScreenshots * 100);
+          logger.info(`📊 Progress: ${totalProcessed}/${totalScreenshots} (${progressPercent}%) - ${batchSuccesses} downloaded, ${batchFailures} failed in this batch`);
         }
       }
 
       // Check if we actually downloaded any screenshots
-      if (downloadedCount === 0) {
+      if (downloadedCount === 0 && skippedCount === 0) {
         logger.error('❌ No screenshots were successfully downloaded from the baseline build');
+        if (errorCount > 0) {
+          logger.info(`💡 ${errorCount} screenshots had errors - check download URLs and network connection`);
+        }
         logger.info('💡 This usually means the build failed or screenshots have no download URLs');
         logger.info('💡 Try using a successful build ID, or run without --baseline-build to create local baselines');
         return null;
@@ -258,9 +312,16 @@ export class TddService {
       };
       const metadataPath = join(this.baselinePath, 'metadata.json');
       writeFileSync(metadataPath, JSON.stringify(this.baselineData, null, 2));
-      if (skippedCount > 0) {
-        const actualDownloads = downloadedCount - skippedCount;
-        logger.info(`✅ Baseline ready - ${actualDownloads} downloaded, ${skippedCount} skipped (matching SHA) - ${downloadedCount}/${buildDetails.screenshots.length} total`);
+
+      // Final summary
+      const actualDownloads = downloadedCount - skippedCount;
+      const totalAttempted = downloadedCount + errorCount;
+      if (skippedCount > 0 || errorCount > 0) {
+        let summaryParts = [];
+        if (actualDownloads > 0) summaryParts.push(`${actualDownloads} downloaded`);
+        if (skippedCount > 0) summaryParts.push(`${skippedCount} skipped (matching SHA)`);
+        if (errorCount > 0) summaryParts.push(`${errorCount} failed`);
+        logger.info(`✅ Baseline ready - ${summaryParts.join(', ')} - ${totalAttempted}/${buildDetails.screenshots.length} total`);
       } else {
         logger.info(`✅ Baseline downloaded successfully - ${downloadedCount}/${buildDetails.screenshots.length} screenshots`);
       }

package/dist/services/test-runner.js

@@ -138,7 +138,8 @@ export class TestRunner extends BaseService {
           environment: options.environment || 'test',
           commit_sha: options.commit,
           commit_message: options.message,
-          github_pull_request_number: options.pullRequestNumber
+          github_pull_request_number: options.pullRequestNumber,
+          parallel_id: options.parallelId
         });
         this.logger.debug(`Build created with ID: ${buildResult.id}`);
 

package/dist/services/uploader.js

@@ -51,6 +51,7 @@ export function createUploader({
     environment = 'production',
     threshold,
     pullRequestNumber,
+    parallelId,
     onProgress = () => {}
   }) {
     try {
@@ -101,7 +102,8 @@ export function createUploader({
         commit_message: message,
         environment,
         threshold,
-        github_pull_request_number: pullRequestNumber
+        github_pull_request_number: pullRequestNumber,
+        parallel_id: parallelId
       };
       const build = await api.createBuild(buildInfo);
       const buildId = build.id;
@@ -219,7 +221,6 @@ export function createUploader({
       if (build.status === 'failed') {
         throw new UploadError(`Build failed: ${build.error || 'Unknown error'}`);
       }
-      await new Promise(resolve => setTimeout(resolve, 2000));
     }
     throw new TimeoutError(`Build timed out after ${timeout}ms`, {
       buildId,

package/dist/types/commands/finalize.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Finalize command implementation
+ * @param {string} parallelId - Parallel ID to finalize
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export function finalizeCommand(parallelId: string, options?: any, globalOptions?: any): Promise<void>;
+/**
+ * Validate finalize options
+ * @param {string} parallelId - Parallel ID to finalize
+ * @param {Object} options - Command options
+ */
+export function validateFinalizeOptions(parallelId: string, _options: any): string[];

package/dist/types/services/api-service.d.ts

@@ -76,4 +76,10 @@ export class ApiService {
      * @returns {Promise<Object>} Token context data
      */
     getTokenContext(): Promise<any>;
+    /**
+     * Finalize a parallel build
+     * @param {string} parallelId - Parallel ID to finalize
+     * @returns {Promise<Object>} Finalization result
+     */
+    finalizeParallelBuild(parallelId: string): Promise<any>;
 }

package/dist/types/services/uploader.d.ts

@@ -8,7 +8,7 @@ export function createUploader({ apiKey, apiUrl, userAgent, command, upload: upl
     command: any;
     upload?: {};
 }, options?: {}): {
-    upload: ({ screenshotsDir, buildName, branch, commit, message, environment, threshold, pullRequestNumber, onProgress, }: {
+    upload: ({ screenshotsDir, buildName, branch, commit, message, environment, threshold, pullRequestNumber, parallelId, onProgress, }: {
         screenshotsDir: any;
         buildName: any;
         branch: any;
@@ -17,6 +17,7 @@ export function createUploader({ apiKey, apiUrl, userAgent, command, upload: upl
         environment?: string;
         threshold: any;
         pullRequestNumber: any;
+        parallelId: any;
         onProgress?: () => void;
     }) => Promise<{
         success: boolean;

package/dist/types/utils/environment-config.d.ts

@@ -37,6 +37,11 @@ export function getServerUrl(): string | undefined;
  * @returns {string|undefined} Build ID
  */
 export function getBuildId(): string | undefined;
+/**
+ * Get parallel ID from environment
+ * @returns {string|undefined} Parallel ID
+ */
+export function getParallelId(): string | undefined;
 /**
  * Check if TDD mode is enabled
  * @returns {boolean} Whether TDD mode is enabled

package/dist/utils/config-loader.js

@@ -1,6 +1,6 @@
 import { cosmiconfigSync } from 'cosmiconfig';
 import { resolve } from 'path';
-import { getApiToken, getApiUrl } from './environment-config.js';
+import { getApiToken, getApiUrl, getParallelId } from './environment-config.js';
 const DEFAULT_CONFIG = {
   // API Configuration
   apiKey: getApiToken(),
@@ -62,8 +62,10 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
   // 2. Override with environment variables
   const envApiKey = getApiToken();
   const envApiUrl = getApiUrl();
+  const envParallelId = getParallelId();
   if (envApiKey) config.apiKey = envApiKey;
   if (envApiUrl !== 'https://vizzly.dev') config.apiUrl = envApiUrl;
+  if (envParallelId) config.parallelId = envParallelId;
 
   // 3. Apply CLI overrides (highest priority)
   applyCLIOverrides(config, cliOverrides);
@@ -85,6 +87,7 @@ function applyCLIOverrides(config, cliOverrides = {}) {
   if (cliOverrides.branch) config.build.branch = cliOverrides.branch;
   if (cliOverrides.commit) config.build.commit = cliOverrides.commit;
   if (cliOverrides.message) config.build.message = cliOverrides.message;
+  if (cliOverrides.parallelId) config.parallelId = cliOverrides.parallelId;
 
   // Server overrides
   if (cliOverrides.port) config.server.port = parseInt(cliOverrides.port, 10);

package/dist/utils/environment-config.js

@@ -59,6 +59,14 @@ export function getBuildId() {
   return process.env.VIZZLY_BUILD_ID;
 }
 
+/**
+ * Get parallel ID from environment
+ * @returns {string|undefined} Parallel ID
+ */
+export function getParallelId() {
+  return process.env.VIZZLY_PARALLEL_ID;
+}
+
 /**
  * Check if TDD mode is enabled
  * @returns {boolean} Whether TDD mode is enabled
@@ -88,6 +96,7 @@ export function getAllEnvironmentConfig() {
     enabled: isVizzlyEnabled(),
     serverUrl: getServerUrl(),
     buildId: getBuildId(),
+    parallelId: getParallelId(),
     tddMode: isTddMode()
   };
 }

package/docs/api-reference.md

@@ -289,6 +289,7 @@ Upload screenshots from a directory.
 - `--token <token>` - API token override
 - `--wait` - Wait for build completion
 - `--upload-all` - Upload all screenshots without SHA deduplication
+- `--parallel-id <id>` - Unique identifier for parallel test execution
 
 **Exit Codes:**
 - `0` - Success (all approved or no changes)
@@ -321,6 +322,9 @@ Run tests with Vizzly integration.
 - `--upload-timeout <ms>` - Upload wait timeout in ms (default: from config or 30000)
 - `--upload-all` - Upload all screenshots without SHA deduplication
 
+*Parallel Execution:*
+- `--parallel-id <id>` - Unique identifier for parallel test execution
+
 *Development & Testing:*
 - `--allow-no-token` - Allow running without API token
 - `--token <token>` - API token override
@@ -403,6 +407,26 @@ Check build status.
 - `1` - Build has changes requiring review
 - `2` - Build failed or error
 
+### `vizzly finalize <parallel-id>`
+
+Finalize a parallel build after all shards complete.
+
+**Arguments:**
+- `<parallel-id>` - Parallel ID to finalize
+
+**Description:**
+When using parallel execution with `--parallel-id`, all test shards contribute screenshots to the same shared build. After all shards complete successfully, use this command to finalize the build and trigger comparison processing.
+
+**Example:**
+```bash
+# After all parallel shards complete
+vizzly finalize "ci-run-123-attempt-1"
+```
+
+**Exit Codes:**
+- `0` - Build finalized successfully
+- `1` - Finalization failed or error
+
 ### `vizzly doctor`
 
 Run environment diagnostics.
@@ -486,6 +510,9 @@ Configuration loaded via cosmiconfig in this order:
 - `VIZZLY_API_URL` - API base URL override
 - `VIZZLY_LOG_LEVEL` - Logger level (`debug`, `info`, `warn`, `error`)
 
+**Parallel Builds:**
+- `VIZZLY_PARALLEL_ID` - Unique identifier for parallel test execution
+
 **Git Information Override (CI/CD Enhancement):**
 - `VIZZLY_COMMIT_SHA` - Override detected commit SHA
 - `VIZZLY_COMMIT_MESSAGE` - Override detected commit message

package/docs/test-integration.md

@@ -209,6 +209,15 @@ vizzly run "npm test" --upload-all
 vizzly run "npm test" --threshold 0.02
 ```
 
+### Parallel Execution
+
+**`--parallel-id <id>`** - Unique identifier for parallel test execution
+```bash
+vizzly run "npm test" --parallel-id "ci-run-123"
+```
+
+When using parallel execution, multiple test runners can contribute screenshots to the same build. This is particularly useful for CI/CD pipelines with parallel jobs.
+
 ### Development Options
 
 For TDD mode, use the dedicated `vizzly tdd` command. See [TDD Mode Guide](./tdd-mode.md) for details.
@@ -283,6 +292,43 @@ jobs:
 
 **Enhanced Git Information:** The `VIZZLY_*` environment variables ensure accurate git metadata is captured in your builds, avoiding issues with merge commits that can occur in CI environments.
 
+### Parallel Builds in CI
+
+For parallel test execution, use `--parallel-id` to ensure all shards contribute to the same build:
+
+```yaml
+# GitHub Actions with parallel matrix
+jobs:
+  e2e-tests:
+    strategy:
+      matrix:
+        shard: [1/4, 2/4, 3/4, 4/4]
+    steps:
+      - name: Run tests with Vizzly
+        run: |
+          npx vizzly run "npm test -- --shard=${{ matrix.shard }}" \
+            --parallel-id="${{ github.run_id }}-${{ github.run_attempt }}"
+        env:
+          VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
+
+  finalize-e2e:
+    needs: e2e-tests
+    runs-on: ubuntu-latest
+    if: always() && needs.e2e-tests.result == 'success'
+    steps:
+      - name: Finalize parallel build
+        run: |
+          npx vizzly finalize "${{ github.run_id }}-${{ github.run_attempt }}"
+        env:
+          VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
+```
+
+**How Parallel Builds Work:**
+1. All shards with the same `--parallel-id` contribute to one shared build
+2. First shard creates the build, subsequent shards add screenshots to it
+3. After all shards complete, use `vizzly finalize` to trigger comparison processing
+4. Use GitHub's run ID + attempt for uniqueness across workflow runs
+
 ### GitLab CI
 
 ```yaml
@@ -294,6 +340,29 @@ visual-tests:
     - npx vizzly run "npm test" --wait
   variables:
     VIZZLY_TOKEN: $VIZZLY_TOKEN
+
+# Parallel execution example
+visual-tests-parallel:
+  stage: test
+  parallel:
+    matrix:
+      - SHARD: "1/4"
+      - SHARD: "2/4"
+      - SHARD: "3/4"
+      - SHARD: "4/4"
+  script:
+    - npm ci
+    - npx vizzly run "npm test -- --shard=$SHARD" --parallel-id "$CI_PIPELINE_ID-$CI_JOB_ID"
+  variables:
+    VIZZLY_TOKEN: $VIZZLY_TOKEN
+
+finalize-visual-tests:
+  stage: finalize
+  needs: ["visual-tests-parallel"]
+  script:
+    - npx vizzly finalize "$CI_PIPELINE_ID-$CI_JOB_ID"
+  variables:
+    VIZZLY_TOKEN: $VIZZLY_TOKEN
 ```
 
 ## Advanced Usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",