@vizzly-testing/cli 0.34.0 → 0.35.1

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import 'dotenv/config';
-import { program } from 'commander';
+import { existsSync, statSync } from 'node:fs';
+import { Option, program } from 'commander';
 import { apiCommand, validateApiOptions } from './commands/api.js';
 import { baselinesCommand, validateBaselinesOptions } from './commands/baselines.js';
 import { buildsCommand, validateBuildsOptions } from './commands/builds.js';
@@ -52,7 +53,7 @@ const formatHelp = (cmd, helper) => {
     lines.push(`   ${c.gray('Visual regression testing from your terminal')}`);
   } else {
     // Compact header for subcommands
-    lines.push(`  ${c.brand.amber(c.bold('vizzly'))} ${c.white(cmd.name())}`);
+    lines.push(`  ${c.brand.amber(c.bold(commandPath(cmd)))}`);
     let desc = cmd.description();
     if (desc) {
       lines.push(`  ${c.gray(desc)}`);
@@ -84,7 +85,7 @@ const formatHelp = (cmd, helper) => {
         key: 'setup',
         icon: '▸',
         title: 'Setup',
-        names: ['init', 'doctor', 'config', 'baselines']
+        names: ['init', 'doctor', 'config', 'baselines', 'project']
       }, {
         key: 'advanced',
         icon: '▸',
@@ -174,7 +175,7 @@ const formatHelp = (cmd, helper) => {
     lines.push(`  ${c.brand.amber('▸')} ${c.bold('Quick Start')}`);
     lines.push('');
     lines.push(`      ${c.dim('# Local visual review')}`);
-    lines.push(`      ${c.gray('$')} ${c.white('vizzly tdd start')}`);
+    lines.push(`      ${c.gray('$')} ${c.white('vizzly tdd start --open')}`);
     lines.push('');
     lines.push(`      ${c.dim('# CI pipeline')}`);
     lines.push(`      ${c.gray('$')} ${c.white('vizzly run "pnpm test" --wait')}`);
@@ -205,8 +206,21 @@ const formatHelp = (cmd, helper) => {
   lines.push('');
   return lines.join('\n');
 };
+function commandPath(cmd) {
+  let names = [];
+  let current = cmd;
+  while (current) {
+    let name = current.name();
+    if (name) {
+      names.unshift(name);
+    }
+    current = current.parent;
+  }
+  return names.join(' ');
+}
 function extractGlobalOptionsFromArgv(argv, commandNames = null) {
   let configPath = null;
+  let tokenArg = null;
   let verboseMode = false;
   let logLevelArg = null;
   let jsonArg = null;
@@ -214,6 +228,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 +253,7 @@ function extractGlobalOptionsFromArgv(argv, commandNames = null) {
   }
   return {
     configPath,
+    tokenArg,
     verboseMode,
     logLevelArg,
     jsonArg
@@ -252,14 +272,139 @@ function normalizeJsonArgv(argv, commandNames) {
   }
   return normalizedArgv;
 }
+function findNestedCommandRequest(args, startIndex, subcommandNames, parentName) {
+  if (!subcommandNames?.size) {
+    return null;
+  }
+  let valueOptions = new Set(['-c', '--config', '--token', '--log-level']);
+  for (let i = startIndex; i < args.length; i++) {
+    let arg = args[i];
+    if (arg === '--') {
+      return null;
+    }
+    if (valueOptions.has(arg)) {
+      i++;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      continue;
+    }
+    return {
+      name: arg,
+      known: subcommandNames.has(arg),
+      helpCommand: `vizzly ${parentName} --help`
+    };
+  }
+  return null;
+}
+function findRequestedCommand(argv, commandNames, nestedCommandNames = new Map()) {
+  let valueOptions = new Set(['-c', '--config', '--token', '--log-level']);
+  let args = argv.slice(2);
+  let jsonValueCandidate = null;
+  for (let i = 0; i < args.length; i++) {
+    let arg = args[i];
+    if (arg === '--') {
+      return null;
+    }
+    if (arg === '--json') {
+      let nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith('-') && !commandNames.has(nextArg)) {
+        jsonValueCandidate = jsonValueCandidate || nextArg;
+        i++;
+      }
+      continue;
+    }
+    if (valueOptions.has(arg)) {
+      i++;
+      continue;
+    }
+    if (arg.startsWith('--json=')) {
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      continue;
+    }
+    let known = commandNames.has(arg);
+    if (known) {
+      let nestedRequest = findNestedCommandRequest(args, i + 1, nestedCommandNames.get(arg), arg);
+      if (nestedRequest && !nestedRequest.known) {
+        return nestedRequest;
+      }
+    }
+    return {
+      name: arg,
+      known
+    };
+  }
+  if (jsonValueCandidate) {
+    return {
+      name: jsonValueCandidate,
+      known: false
+    };
+  }
+  return null;
+}
+function getGlobalOptions() {
+  let options = program.opts();
+  return {
+    ...options,
+    noColor: options.noColor || options.color === false
+  };
+}
+function reportValidationErrors(errors) {
+  if (output.isJson()) {
+    output.error('Validation errors', null, {
+      errors
+    });
+  } else {
+    output.error('Validation errors:');
+    for (let error of errors) {
+      output.printErr(`  - ${error}`);
+    }
+  }
+  process.exit(1);
+}
+function formatCommanderError(message) {
+  return message.replace(/^error:\s*/, '').trim();
+}
+function writeCommanderError(text) {
+  let message = formatCommanderError(text);
+  if (!message) {
+    return;
+  }
+  if (output.isJson()) {
+    if (message.startsWith('(')) {
+      return;
+    }
+    output.error(message);
+  } else {
+    process.stderr.write(text);
+    if (!text.endsWith('\n')) {
+      process.stderr.write('\n');
+    }
+  }
+}
 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 (shorthand for --log-level debug)').option('--log-level <level>', 'Log level: debug, info, warn, error (default: info, or VIZZLY_LOG_LEVEL env var)').option('--json [fields]', 'JSON output, optionally specify fields (e.g., --json id,status,branch)').option('--color', 'Force colored output (even in non-TTY)').option('--no-color', 'Disable colored output').option('--strict', 'Fail on any error (default: be resilient, warn on non-critical issues)').configureHelp({
   formatHelp
 });
+program.configureOutput({
+  writeErr: writeCommanderError
+});
+program.showHelpAfterError('(Run vizzly --help for available commands)');
+program.showSuggestionAfterError();
+program.exitOverride();
 
 // Load plugins before defining commands
 // We need to manually parse to get the config option early
 let {
   configPath,
+  tokenArg,
   verboseMode,
   logLevelArg,
   jsonArg
@@ -280,9 +425,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);
@@ -304,34 +451,41 @@ try {
   output.debug(`Plugin loading failed: ${error.message}`);
 }
 program.command('init').description('Initialize Vizzly in your project').option('--force', 'Overwrite existing configuration').option('--agent-skill', 'Install the repo-local Vizzly agent skill').option('--agent-guidance', 'Add Vizzly guidance to this project AGENTS.md and install the agent skill').option('--skip-agent-skill', 'Skip the Vizzly agent skill prompt').action(async options => {
-  let globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   await init({
     ...globalOptions,
     ...options,
     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 = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateUploadOptions(path, options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
+    reportValidationErrors(validationErrors);
+  }
+  if (!existsSync(path)) {
+    output.error(`Path does not exist: ${path}`);
     process.exit(1);
   }
-  await uploadCommand(path, options, globalOptions);
+  if (!statSync(path).isDirectory()) {
+    output.error(`Path is not a directory: ${path}`);
+    process.exit(1);
+  }
+  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
-const tddCmd = program.command('tdd').description('Run tests in TDD mode with local visual review');
+const tddCmd = program.command('tdd').description('Run tests in TDD mode with local visual review').showHelpAfterError('(Run vizzly tdd --help for available commands)').showSuggestionAfterError();
 
 // TDD Start - Background server
-tddCmd.command('start').description('Start background TDD server with dashboard').option('--port <port>', 'Port for TDD server', '47392').option('--open', 'Open dashboard in browser').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--token <token>', 'API token override').option('--daemon-child', 'Internal: run as daemon child process').action(async options => {
-  const globalOptions = program.opts();
+tddCmd.command('start').description('Start background TDD server with dashboard').option('--port <port>', 'Port for TDD server').option('--open', 'Open dashboard in browser').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--token <token>', 'API token override').addOption(new Option('--daemon-child', 'Internal: run as daemon child process').hideHelp()).action(async options => {
+  let globalOptions = getGlobalOptions();
 
   // If this is a daemon child process, run the server directly
   if (options.daemonChild) {
@@ -340,45 +494,45 @@ tddCmd.command('start').description('Start background TDD server with dashboard'
   }
   let validationErrors = validateTddStartOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await tddStartCommand(options, globalOptions);
 });
 
 // TDD Stop - Kill background server
-tddCmd.command('stop').description('Stop background TDD server').action(async options => {
-  const globalOptions = program.opts();
+tddCmd.command('stop').description('Stop background TDD server').option('--port <port>', 'Port for TDD server').action(async options => {
+  let globalOptions = getGlobalOptions();
+  let validationErrors = validateTddStartOptions(options);
+  if (validationErrors.length > 0) {
+    reportValidationErrors(validationErrors);
+  }
   await tddStopCommand(options, globalOptions);
 });
 
 // TDD Status - Check server status
-tddCmd.command('status').description('Check TDD server status').action(async options => {
-  const globalOptions = program.opts();
+tddCmd.command('status').description('Check TDD server status').option('--port <port>', 'Port for TDD server').action(async options => {
+  let globalOptions = getGlobalOptions();
+  let validationErrors = validateTddStartOptions(options);
+  if (validationErrors.length > 0) {
+    reportValidationErrors(validationErrors);
+  }
   await tddStatusCommand(options, globalOptions);
 });
 
 // TDD List - List all running servers (for menubar app integration)
 tddCmd.command('list').description('List all running TDD servers').action(async options => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   await tddListCommand(options, globalOptions);
 });
 
 // TDD Run - One-off test run with ephemeral server (generates static report)
-tddCmd.command('run <command>').description('Run tests once in TDD mode with local visual review').option('--port <port>', 'Port for TDD server', '47392').option('--branch <branch>', 'Git branch override').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('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--set-baseline', 'Accept current screenshots as new baseline (overwrites existing)').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--no-open', 'Skip opening report in browser').action(async (command, options) => {
-  const globalOptions = program.opts();
+tddCmd.command('run <command>').description('Run tests once in TDD mode with local visual review').option('--port <port>', 'Port for TDD server').option('--branch <branch>', 'Git branch override').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('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--set-baseline', 'Accept current screenshots as new baseline (overwrites existing)').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--no-open', 'Skip opening report in browser').action(async (command, options) => {
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateTddOptions(command, options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   const {
     result,
@@ -403,8 +557,8 @@ tddCmd.command('run <command>').description('Run tests once in TDD mode with loc
   process.once('SIGINT', sigintHandler);
   process.once('SIGTERM', sigtermHandler);
 
-  // If there are comparisons, generate static report
-  const hasComparisons = result?.comparisons?.length > 0;
+  // If the run captured screenshots, generate a static report for review.
+  let hasComparisons = result?.screenshotsCaptured > 0 || result?.comparisons?.length > 0 || result?.summary?.total > 0;
   if (hasComparisons) {
     // Note: Tests have completed at this point, so report-data.json is stable.
     // The report reflects the final state of all comparisons.
@@ -430,16 +584,12 @@ tddCmd.command('run <command>').description('Run tests once in TDD mode with loc
   process.exit(result?.exitCode || 0);
 });
 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('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--batch-size <n>', 'Upload batch size', Number).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', Number).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();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateRunOptions(command, options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   try {
     const result = await runCommand(command, options, globalOptions);
@@ -452,16 +602,12 @@ program.command('run').description('Run tests with Vizzly integration').argument
   }
 });
 program.command('status').description('Check the status of a build').argument('<build-id>', 'Build ID to check status for').action(async (buildId, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateStatusOptions(buildId, options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await statusCommand(buildId, options, globalOptions);
 });
@@ -476,16 +622,12 @@ Examples:
   $ vizzly builds -b abc123 --comparisons  # Include comparisons
   $ vizzly builds --json                   # Output as JSON for scripting
 `).action(async options => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateBuildsOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await buildsCommand(options, globalOptions);
 });
@@ -499,20 +641,16 @@ Examples:
   $ vizzly comparisons --status changed    # Only changed comparisons
   $ vizzly comparisons --json              # Output as JSON for scripting
 `).action(async options => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateComparisonsOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await comparisonsCommand(options, globalOptions);
 });
-let contextCmd = program.command('context').description('Fetch build and diff context');
+let contextCmd = program.command('context').description('Fetch build and diff context').showHelpAfterError('(Run vizzly context --help for available commands)').showSuggestionAfterError();
 contextCmd.command('build').description('Fetch build context').argument('<build-id>', 'Build ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('--agent', 'Output compact context for LLM agents').option('--full', 'Return the full build context payload with --agent --json').option('--include <items>', 'Add detail to compact agent JSON: screenshots,diffs,comments').addHelpText('after', `
 Examples:
   $ vizzly context build abc123
@@ -522,14 +660,10 @@ Examples:
   $ vizzly context build abc123 --agent --json --include diffs,comments
   $ vizzly context build abc123 --agent --json --full
 `).action(async (buildId, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   const validationErrors = validateContextBuildOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await contextBuildCommand(buildId, options, globalOptions);
 });
@@ -540,14 +674,10 @@ Examples:
   $ vizzly context comparison def456 --similar-limit 5 --recent-limit 5
   $ vizzly context comparison def456 --json
 `).action(async (comparisonId, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   const validationErrors = validateContextComparisonOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await contextComparisonCommand(comparisonId, options, globalOptions);
 });
@@ -558,14 +688,10 @@ Examples:
   $ vizzly context screenshot Dashboard --project storybook --org acme
   $ vizzly context screenshot Dashboard --json
 `).action(async (name, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   const validationErrors = validateContextScreenshotOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await contextScreenshotCommand(name, options, globalOptions);
 });
@@ -575,14 +701,10 @@ Examples:
   $ vizzly context similar fp-dashboard --project storybook --org acme
   $ vizzly context similar fp-dashboard --json
 `).action(async (fingerprintHash, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   const validationErrors = validateContextSimilarOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await contextSimilarCommand(fingerprintHash, options, globalOptions);
 });
@@ -593,28 +715,20 @@ Examples:
   $ vizzly context review-queue --limit 10
   $ vizzly context review-queue --json
 `).action(async options => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   const validationErrors = validateContextReviewQueueOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await contextReviewQueueCommand(options, globalOptions);
 });
 program.command('config').description('Display current configuration').argument('[key]', 'Specific config key to get (dot notation, e.g., comparison.threshold)').action(async (key, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateConfigOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await configCommand(key, options, globalOptions);
 });
@@ -627,16 +741,12 @@ Examples:
 
 Note: Baselines are stored locally in .vizzly/baselines/ during TDD mode.
 `).action(async options => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateBaselinesOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await baselinesCommand(options, globalOptions);
 });
@@ -651,20 +761,16 @@ Examples:
 Note: POST is restricted to approve, reject, and comment endpoints.
 Most operations have dedicated commands (builds, comparisons, approve, etc.).
 `).action(async (endpoint, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateApiOptions(endpoint, options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await apiCommand(endpoint, options, globalOptions);
 });
-program.command('approve').description('Approve a comparison').argument('<comparison-id>', 'Comparison ID to approve (UUID format)').option('-m, --comment <message>', 'Optional comment explaining the approval').addHelpText('after', `
+program.command('approve').description('Approve a comparison').argument('<comparison-id>', 'Comparison ID to approve').option('-m, --comment <message>', 'Optional comment explaining the approval').addHelpText('after', `
 Examples:
   $ vizzly approve abc123-def456-7890     # Approve a comparison
   $ vizzly approve abc123 -m "LGTM"       # Approve with comment
@@ -675,18 +781,14 @@ Workflow:
   2. Review the changes in the web UI or via URLs in the output
   3. Approve: vizzly approve <comparison-id>
 `).action(async (comparisonId, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   const validationErrors = validateApproveOptions(comparisonId, options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await approveCommand(comparisonId, options, globalOptions);
 });
-program.command('reject').description('Reject a comparison').argument('<comparison-id>', 'Comparison ID to reject (UUID format)').option('-r, --reason <message>', 'Required reason for rejection').addHelpText('after', `
+program.command('reject').description('Reject a comparison').argument('<comparison-id>', 'Comparison ID to reject').option('-r, --reason <message>', 'Required reason for rejection').addHelpText('after', `
 Examples:
   $ vizzly reject abc123 -r "Button color is wrong"
   $ vizzly reject abc123 --reason "Needs design review"
@@ -697,18 +799,14 @@ Workflow:
   2. Review the changes in the web UI or via URLs in the output
   3. Reject with reason: vizzly reject <comparison-id> -r "reason"
 `).action(async (comparisonId, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   const validationErrors = validateRejectOptions(comparisonId, options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await rejectCommand(comparisonId, options, globalOptions);
 });
-program.command('comment').description('Add a comment to a build').argument('<build-id>', 'Build ID to comment on (UUID format)').argument('<message>', 'Comment message').option('-t, --type <type>', 'Comment type: general, approval, rejection', 'general').addHelpText('after', `
+program.command('comment').description('Add a comment to a build').argument('<build-id>', 'Build ID to comment on').argument('<message>', 'Comment message').option('-t, --type <type>', 'Comment type: general, approval, rejection', 'general').addHelpText('after', `
 Examples:
   $ vizzly comment abc123 "Looks good overall"
   $ vizzly comment abc123 "Approved" -t approval
@@ -719,14 +817,10 @@ Workflow:
   1. Get build ID: vizzly builds --branch main
   2. Add comment: vizzly comment <build-id> "Your message"
 `).action(async (buildId, message, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   const validationErrors = validateCommentOptions(buildId, message, options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await commentCommand(buildId, message, options, globalOptions);
 });
@@ -738,14 +832,10 @@ Examples:
 Note: Shows organizations from your user account (via vizzly login)
 or the single organization for a project token.
 `).action(async options => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   const validationErrors = validateOrgsOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await orgsCommand(options, globalOptions);
 });
@@ -760,18 +850,14 @@ Workflow:
   2. List projects: vizzly projects --org <org-slug>
   3. Query builds: vizzly builds
 `).action(async options => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   const validationErrors = validateProjectsOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await projectsCommand(options, globalOptions);
 });
-let projectCommand = program.command('project').description('Manage the project linked to this local checkout');
+let projectCommand = program.command('project').description('Manage the project linked to this local checkout').showHelpAfterError('(Run vizzly project --help for available commands)').showSuggestionAfterError();
 projectCommand.command('link [selector]').description('Link a Vizzly project for cloud uploads').option('--org <slug>', 'Organization slug').option('--project <slug>', 'Project slug').option('--name <name>', 'Credential name shown in Vizzly').option('--expires-at <iso>', 'Optional token expiration timestamp').addHelpText('after', `
 Examples:
   $ vizzly project link vizzly/storybook
@@ -780,111 +866,85 @@ Examples:
 Note: run "vizzly login" first. The linked credential is project-scoped and is
 used for cloud uploads; your user login remains separate for review actions.
 `).action(async (selector, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
   const validationErrors = validateProjectLinkOptions(selector, options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await projectLinkCommand(selector, 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();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateFinalizeOptions(parallelId, options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await finalizeCommand(parallelId, options, globalOptions);
 });
 program.command('preview').description('Upload static files as a preview for a build').argument('[path]', 'Path to static files (dist/, build/, out/)').option('-b, --build <id>', 'Build ID to attach preview to').option('--base <path>', 'Override auto-detected base path').option('--open', 'Open preview URL in browser after upload').option('--dry-run', 'Show what would be uploaded without uploading').option('--public-link', 'Acknowledge that preview URL grants access to anyone with the link (required for private projects)').option('-x, --exclude <pattern>', 'Exclude files/dirs (repeatable, e.g. -x "*.log" -x "temp/")', (val, prev) => prev ? [...prev, val] : [val]).option('-i, --include <pattern>', 'Override default exclusions (repeatable, e.g. -i package.json -i tests/)', (val, prev) => prev ? [...prev, val] : [val]).action(async (path, options) => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
 
   // Show helpful error if path is missing
   if (!path) {
     output.error('Path to static files is required');
-    output.blank();
-    output.print('  Upload your build output directory:');
-    output.blank();
-    output.print('    vizzly preview ./dist');
-    output.print('    vizzly preview ./build');
-    output.print('    vizzly preview ./out');
-    output.blank();
+    if (!globalOptions.json) {
+      output.blank();
+      output.print('  Upload your build output directory:');
+      output.blank();
+      output.print('    vizzly preview ./dist');
+      output.print('    vizzly preview ./build');
+      output.print('    vizzly preview ./out');
+      output.blank();
+    }
     process.exit(1);
   }
 
   // Validate options
   const validationErrors = validatePreviewOptions(path, options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await previewCommand(path, 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();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateDoctorOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await doctorCommand(options, globalOptions);
 });
 program.command('login').description('Authenticate with your Vizzly account').option('--api-url <url>', 'API URL override').action(async options => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateLoginOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await loginCommand(options, globalOptions);
 });
 program.command('logout').description('Clear stored authentication tokens').option('--api-url <url>', 'API URL override').action(async options => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateLogoutOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await logoutCommand(options, globalOptions);
 });
 program.command('whoami').description('Show current authentication status and user information').option('--api-url <url>', 'API URL override').action(async options => {
-  const globalOptions = program.opts();
+  let globalOptions = getGlobalOptions();
 
   // Validate options
   const validationErrors = validateWhoamiOptions(options);
   if (validationErrors.length > 0) {
-    output.error('Validation errors:');
-    for (let error of validationErrors) {
-      output.printErr(`  - ${error}`);
-    }
-    process.exit(1);
+    reportValidationErrors(validationErrors);
   }
   await whoamiCommand(options, globalOptions);
 });
@@ -893,6 +953,7 @@ program.command('whoami').description('Show current authentication status and us
 // This auto-configures the menubar app so it can find package runners/node
 saveUserPath().catch(() => {});
 let commandNames = new Set(program.commands.map(command => command.name()));
+let nestedCommandNames = new Map(program.commands.map(command => [command.name(), new Set(command.commands.map(subcommand => subcommand.name()))]));
 let normalizedArgv = normalizeJsonArgv(process.argv, commandNames);
 let normalizedGlobals = extractGlobalOptionsFromArgv(normalizedArgv, commandNames);
 output.configure({
@@ -902,4 +963,19 @@ output.configure({
   json: normalizedGlobals.jsonArg,
   resetTimer: false
 });
-program.parse(normalizedArgv);
+let requestedCommand = findRequestedCommand(normalizedArgv, commandNames, nestedCommandNames);
+if (requestedCommand && !requestedCommand.known) {
+  output.error(`unknown command '${requestedCommand.name}'`);
+  if (!output.isJson() && requestedCommand.helpCommand) {
+    output.printErr(`(Run ${requestedCommand.helpCommand} for available commands)`);
+  }
+  process.exit(1);
+}
+try {
+  program.parse(normalizedArgv);
+} catch (error) {
+  if (error.exitCode == null) {
+    output.error('Unexpected CLI error', error);
+  }
+  process.exit(error.exitCode ?? 1);
+}