@vizzly-testing/cli 0.38.1 → 0.39.0

package/README.md

@@ -1,6 +1,6 @@
 # Vizzly CLI
 
-> Visual regression testing from your terminal
+> Reviewed UI context for coding agents and teams
 
 [![package version](https://img.shields.io/npm/v/@vizzly-testing/cli.svg)](https://www.npmjs.com/package/@vizzly-testing/cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -9,272 +9,298 @@
   <img src="./docs/assets/vizzly-mascot-inspector.png" alt="Vizzly bear inspecting a screenshot" width="220" />
 </p>
 
-Vizzly is a visual testing and regression platform for teams that ship UI. It
-captures screenshots from your real tests, compares them to approved baselines,
-and gives you useful review data: meaningful diffs, comments, approvals, build
-status, and preview links.
+Vizzly helps your team and coding agents see what the UI should look like,
+what changed, and what was approved. It keeps screenshots, diffs, and review
+decisions together so you can use that history the next time you change the UI.
 
-This package is the CLI and local SDK surface. Use it to run local visual TDD,
-upload screenshots from CI, generate static reports, and fetch machine-readable
-build or diff data for scripts, automation, and coding agents.
+## Get started
 
-## Quick Start
-
-You need Node.js 22.18 or newer within Node 22, or Node.js 24+.
+You need Node.js 22.18+ on Node 22, or Node.js 24+. From your test project:
 
 ```bash
-pnpm install -g @vizzly-testing/cli
-
-vizzly init
+pnpm add --save-dev @vizzly-testing/cli
+pnpm exec vizzly init
 ```
 
-For agent-friendly repos, install the Vizzly skill and add a short project
-`AGENTS.md` note:
+The wizard creates a config and offers agent guidance and cloud linking.
+It previews file changes before applying them. If Vizzly is already configured,
+init leaves it alone. Edit the config directly to change your setup.
 
-```bash
-vizzly init --agent-guidance
-```
+To create a small config and edit it yourself, use `pnpm exec vizzly init --quick`.
+It keeps existing config and doesn't install dependencies or run tests.
 
-This installs the portable Agent Skills bundle in `.agents/skills/vizzly` and
-adds a small managed block to `AGENTS.md`. Run the same command again after a
-CLI upgrade to refresh both without replacing the rest of `AGENTS.md` or an
-existing Vizzly config.
+Choose a Vizzly client for your test setup, then add screenshot capture.
+This example uses Playwright with the Node.js client:
 
-Use `vizzly init --agent-skill` to install or refresh only the local skill, or
-`vizzly init --skip-agent-skill` when you want config without the agent prompt.
+```javascript
+import { test } from '@playwright/test';
+import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
 
-### TypeScript Configuration
+test('homepage looks correct', async ({ page }) => {
+  await page.goto('/');
+  await vizzlyScreenshot('homepage', await page.screenshot());
+});
+```
 
-Vizzly loads `vizzly.config.ts` with Node's native type stripping. Type
-annotations, interfaces, and `satisfies` work without installing TypeScript.
-Use `import type` for type-only imports and include file extensions when
-importing local helpers, such as `./helpers.ts`.
+The client runs in Node.js and works with any Node-based test runner. You can
+also pass a file path:
 
-Enums, namespaces containing runtime code, and constructor parameter properties
-aren't supported. Replace them with ordinary JavaScript values and assignments.
-Node doesn't apply `tsconfig.json` path aliases when loading your config.
-These restrictions apply to the config and its imports; they don't change how
-your application or tests compile.
+```javascript
+await vizzlyScreenshot('homepage', './screenshots/homepage.png');
+```
 
-### Start Local TDD
+### Review locally
 
-Start the TDD server, run your tests, and open the dashboard at the URL the
-command prints. Add `--open` when you want Vizzly to open the dashboard for
-you. If the default port is busy, Vizzly picks the next available port; use the
-printed `--port` value with `vizzly tdd status` or `vizzly tdd stop`.
+Start the local TDD server, then run your tests in another terminal:
 
 ```bash
-vizzly tdd start --open
-pnpm test -- --watch
+pnpm exec vizzly tdd start --open
+pnpm test -- --watch # Replace this with your test command
 ```
 
-The dashboard shows screenshots, baselines, and diffs as they arrive. Accept or
-reject changes right from the UI.
+The dashboard shows screenshots and diffs as they arrive. Accept or reject
+changes there. If the default port is busy, use the printed port with
+`pnpm exec vizzly tdd status --port <port>` or
+`pnpm exec vizzly tdd stop --port <port>`.
 
-For a one-off local check, wrap the test command with `tdd run`:
+For a single run:
 
 ```bash
-vizzly tdd run "pnpm test" --no-open
-vizzly context build current --source local --json
+pnpm exec vizzly tdd run "pnpm test" --no-open
 ```
 
-That run writes review data under `.vizzly/` and prints a context command you
-can use for follow-up inspection. If screenshots were captured, Vizzly also
-generates `.vizzly/report/index.html`; omit `--no-open` when you want that
-report opened automatically.
+Review data goes in `.vizzly/`. When the run captures screenshots, it also
+creates `.vizzly/report/index.html`. Omit `--no-open` to open the report.
+If the configured port is busy, `tdd run` picks an available one. An explicit
+`--port` uses only that port.
 
-### Run With Cloud Review
-
-Use cloud builds when you want shared baselines, team review, and CI status:
+### Review in the cloud
 
 ```bash
-vizzly login
-vizzly project link your-org/your-project
-vizzly run "pnpm test" --wait
+pnpm exec vizzly login
+pnpm exec vizzly project link your-org/your-project
+pnpm exec vizzly run "pnpm test"
 ```
 
-`vizzly login` authenticates your user account. `vizzly project link` creates a
-project-scoped upload credential for this checkout, which `vizzly run` uses for
-cloud uploads.
+`vizzly login` signs you in. Linking saves the project name in your config and
+keeps the upload token in user storage. Run it again to reuse a saved token.
+Replace `"pnpm test"` with your test command.
 
-`--wait` blocks until Vizzly finishes processing the build. It exits with code
-`1` when visual differences need review.
+If you linked with an older CLI, run `project link` once in each repository to
+save its project selection. Handwritten config may need a manual edit; the
+command prints what to add. Explicit `--token` and `VIZZLY_TOKEN` still work.
 
-In CI, use a project token:
+To upload screenshots you already have:
 
 ```bash
-export VIZZLY_TOKEN=your-project-token
-vizzly run "pnpm test" --wait
+pnpm exec vizzly upload ./screenshots
 ```
 
-### Inspect Builds And Diffs
-
-Use `vizzly context` for human summaries and local `.vizzly` evidence. For cloud
-reviews, agents should discover and call the public API through its schema:
-
-```bash
-vizzly api schema --json
-vizzly api schema sdk.listBuilds --json
-```
+### Run in CI
 
-The `context build --agent` and `context comparison --agent` formats are
-deprecated and scheduled for removal in v0.38.0. Use the schema-driven API for
-cloud evidence; use `vizzly context ... --json` for local evidence.
+Store a project token as a CI secret and pass it as `VIZZLY_TOKEN`. Add `--wait`
+when you want CI to wait for comparison results and fail on visual differences:
 
 ```bash
-# Human-readable cloud build context
-vizzly context build abc123 --source cloud
-
-# Discover cloud evidence operations for an agent workflow
-vizzly api schema sdk.getBuildContext --json
-vizzly api schema getComparisonContext --json
-
-# Local workspace context from .vizzly/
-vizzly context build current --source local
-vizzly context build current --source local --json
-vizzly context screenshot build-detail-screenshots --source local --json
-vizzly context review-queue --source local --json
+export VIZZLY_TOKEN=your-project-token
+pnpm exec vizzly run "pnpm test" --wait
 ```
 
-Use `vizzly api schema` to inspect cloud operation inputs, output fields, and
-pagination before making requests. The old compact `--agent` handoff remains
-available during deprecation, but new cloud workflows should use the schema.
-Use `--json` for machine-readable local context.
-
-Local context is read-only and file-backed. It reads your existing `.vizzly`
-workspace state from TDD runs, including screenshots, diffs, and saved hotspot
-or region metadata.
-
-The `context` commands are read-only. The schema-discovered review API also
-supports explicit decisions when a task asks for them.
+With `--wait`, failed comparisons make the command exit with code `1`.
 
-## Capture Screenshots
-
-Add screenshots to your existing tests:
+## Screenshot options
 
 ```javascript
-import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
-
-test('homepage looks correct', async ({ page }) => {
-  await page.goto('/');
-
-  let screenshot = await page.screenshot();
-  await vizzlyScreenshot('homepage', screenshot, {
-    fullPage: true,
-    requestTimeout: 5000,
-    properties: {
-      theme: 'dark',
-      locale: 'en-US',
-    },
-  });
+let screenshot = await page.screenshot({ fullPage: true });
+await vizzlyScreenshot('checkout', screenshot, {
+  threshold: 2,
+  minClusterSize: 4,
+  fullPage: true,
+  requestTimeout: 5000,
+  properties: { theme: 'dark', locale: 'en-US' },
 });
 ```
 
-`properties` is your key/value metadata bag for baseline grouping, filtering,
-and debugging. Vizzly passes every property through as user metadata; property
-names are never interpreted as options. The supported top-level options are
+Put details like theme or locale in `properties` for baseline grouping and
+filtering. Vizzly keeps these separate from screenshot options and reads image
+dimensions from the screenshot. For local baseline matching, list custom keys
+in `signatureProperties`. For cloud builds, set matching properties in your
+Vizzly project settings. Common top-level options are
 `threshold`, `minClusterSize`, `fullPage`, `requestTimeout`, and `buildId`.
-Vizzly reads width and height from the captured image, so viewport dimensions do
-not need to be included in `properties`.
 
-The client SDK is lightweight. It posts screenshots to the local Vizzly server
-or the cloud build wrapper. It works with any test runner.
+For setup help, see the [Storybook](clients/storybook/README.md),
+[static site](clients/static-site/README.md), [Vitest](clients/vitest/README.md),
+and [Ember](clients/ember/README.md) guides. There are also
+[Ruby](clients/ruby/README.md) and [Swift](clients/swift/README.md) SDKs.
 
-SDKs are available for
-[JavaScript](https://docs.vizzly.dev/integration/sdk/javascript),
-[Ruby](https://docs.vizzly.dev/integration/sdk/ruby),
-[Swift](https://docs.vizzly.dev/integration/sdk/swift), and
-[more](https://docs.vizzly.dev/integration/sdk/overview).
+## Configuration
 
-Already saving screenshots to disk? Pass the file path instead:
+`vizzly init --quick` creates a config with commented examples. Put settings
+there when you want to change a default, or write `vizzly.config.js` yourself:
 
 ```javascript
-await page.screenshot({ path: './screenshots/homepage.png' });
-await vizzlyScreenshot('homepage', './screenshots/homepage.png');
+export default {
+  comparison: {
+    threshold: 2, // CIEDE2000 Delta E color tolerance.
+  },
+};
 ```
 
-Or upload an existing folder of screenshots:
+Cloud comparisons use your project's settings unless you override them in
+config, environment variables, or command options. Local comparisons use the
+CLI defaults.
+
+Existing config is kept, including TypeScript, rc files, and `package.json`.
+Use `--config <path>` to choose a config or a new destination. `--force`
+replaces the selected config; in `package.json`, it replaces only `vizzly`.
+
+For TypeScript, use `vizzly.config.ts`. Node strips the types, so you don't need
+a separate compiler. Use `import type` for types and include extensions in local
+imports, like `./helpers.ts`. Enums, namespaces with runtime code, constructor
+parameter properties, and `tsconfig.json` path aliases won't work in the config
+or files it imports.
+
+### Coding agents and scripts
+
+Install the Vizzly skill and a short `AGENTS.md` note:
 
 ```bash
-vizzly upload ./screenshots --threshold 2 --min-cluster-size 4 --batch-size 10 --upload-timeout 60000
+pnpm exec vizzly init --agent-guidance
 ```
 
-`--batch-size` controls how many screenshots are uploaded per request.
-`--upload-timeout` controls the upload client's timeout, including how long
-`--wait` polls for build processing.
+This adds `.agents/skills/vizzly` and a note in `AGENTS.md`, keeping other
+guidance. Use `--agent-skill` to install only the skill during setup.
+These flags don't open the wizard or update an existing Vizzly setup.
+`--skip-agent-skill` skips agent setup unless you also request `--agent-guidance`.
 
-When `vizzly run` sends screenshots to Vizzly, the CLI first asks the API to
-resolve each screenshot by SHA. If Vizzly already has the image bytes, the CLI
-creates the screenshot record without re-uploading the image. CI workflows can
-force every screenshot through with `--upload-all`. Parallel jobs should use the
-same stable ID, then finalize that ID after every shard completes:
+Use `context` to read local results. For cloud results, check the API schema
+to find the available requests:
 
 ```bash
-vizzly run "pnpm test" --upload-all --parallel-id "$GITHUB_RUN_ID"
-vizzly finalize "$GITHUB_RUN_ID"
+pnpm exec vizzly context build current --source local --json
+pnpm exec vizzly context review-queue --source local --json
+pnpm exec vizzly api schema --json
+pnpm exec vizzly api schema sdk.getBuildContext --json
 ```
 
-For smoke jobs where cloud credentials are intentionally unavailable, add
-`--allow-no-token` to `vizzly run` and Vizzly will keep the local screenshot
-server path working without creating a cloud build.
+The schema lists inputs, output fields, and how to fetch more results. The old
+`context build --agent` and `context comparison --agent` formats are deprecated.
+Use the API schema for new cloud workflows and `context --json` for local data.
+See the [JSON reference](docs/json-output.md) for output formats and scripts.
 
-## Configuration
+### Parallel CI and uploads
 
-Generate a config file:
+Vizzly reuses images it already has by SHA. Add `--upload-all` to send every
+image. For parallel jobs, use the same ID for every shard and finalize it when
+they all finish:
 
 ```bash
-vizzly init
+pnpm exec vizzly run "pnpm test" --parallel-id "$GITHUB_RUN_ID"
+pnpm exec vizzly finalize "$GITHUB_RUN_ID"
 ```
 
-To teach project agents the Vizzly evidence workflow, add the repo-local skill
-and AGENTS.md guidance:
+Use `--batch-size` to set how many screenshots upload per request.
+`--upload-timeout` limits how long `--wait` waits for build processing; it
+doesn't set the HTTP upload timeout. You can also set
+`--threshold` and `--min-cluster-size`. If CI has no cloud token,
+`vizzly run --allow-no-token` lets your test command run without starting Vizzly.
 
-```bash
-vizzly init --agent-guidance
-```
+## Commands
 
-Or create `vizzly.config.js` manually:
+Use `pnpm exec vizzly --help` to see what's available in your project, or add
+`--help` to a command for its options. These are the built-in commands; run them
+with `pnpm exec` when Vizzly is installed locally.
 
-```javascript
-export default {
-  comparison: {
-    // CIEDE2000 Delta E. 0 is exact. 2 is a good default.
-    threshold: 2.0,
-  },
-};
-```
+<details>
+<summary>Setup and accounts</summary>
 
-## Commands
+| Command | What it does |
+| --- | --- |
+| `vizzly init` | Walk through setup. Use `--quick` to create config without questions. |
+| `vizzly config [key]` | Show your current config. |
+| `vizzly project link <org>/<project>` | Link this checkout to a cloud project. |
+| `vizzly orgs` | List your organizations. |
+| `vizzly projects` | List projects you can access. |
+| `vizzly login` | Sign in through the browser. |
+| `vizzly logout` | Clear your saved login. |
+| `vizzly whoami` | Check your account and authentication status. |
+| `vizzly doctor` | Check your setup. |
+
+</details>
+
+<details>
+<summary>Local review</summary>
+
+| Command | What it does |
+| --- | --- |
+| `vizzly tdd start` | Start the local server and dashboard. |
+| `vizzly tdd status` | Check this project's local server. |
+| `vizzly tdd list` | List running local servers. |
+| `vizzly tdd stop` | Stop this project's local server. |
+| `vizzly tdd run "command"` | Run tests once and save local review data. |
+| `vizzly tdd screenshots list` | List captures from the latest local run. |
+| `vizzly tdd screenshots latest [name]` | Print the latest capture's image path. |
+| `vizzly tdd screenshots show <id-or-name>` | Show local capture details and the current image path. |
+| `vizzly tdd screenshots accept <id-or-name>` | Save a local capture as its baseline. |
+| `vizzly baselines` | List local baselines, or inspect one with `--info <name>`. |
+
+</details>
+
+<details>
+<summary>Cloud builds</summary>
+
+| Command | What it does |
+| --- | --- |
+| `vizzly run "command"` | Run tests and upload for cloud review. |
+| `vizzly upload <dir>` | Upload screenshots. |
+| `vizzly finalize <parallel-id>` | Finish a cloud build after all shards complete. |
+| `vizzly preview <path>` | Upload a static preview for a cloud build; private projects need `--public-link`. |
+| `vizzly status <build-id>` | Check cloud build status. |
+| `vizzly builds` | List builds, or fetch one with `--build <id>`. |
+| `vizzly comparisons --build <build-id>` | List a build's comparisons; also supports `--id` or `--name` queries. |
+
+</details>
+
+<details>
+<summary>Build and screenshot context</summary>
+
+| Command | What it does |
+| --- | --- |
+| `vizzly context build <build-id>` | Read build context. |
+| `vizzly context comparison <comparison-id>` | Read comparison context. |
+| `vizzly context screenshot <name>` | Read screenshot history. |
+| `vizzly context similar <fingerprint-hash>` | Find cloud comparisons with similar diffs. |
+| `vizzly context review-queue` | Read comparisons waiting for review. |
+
+</details>
+
+<details>
+<summary>Review decisions</summary>
 
 | Command | What it does |
 | --- | --- |
-| `vizzly tdd start` | Start the local TDD server and dashboard. |
-| `vizzly tdd status` | Check the local TDD server for this project. |
-| `vizzly tdd list` | List running local TDD servers. |
-| `vizzly tdd stop` | Stop the local TDD server for this project. |
-| `vizzly tdd run "cmd"` | Run tests once and write local review data under `.vizzly/`. |
-| `vizzly run "cmd"` | Run tests with cloud build and review integration. |
-| `vizzly context ...` | Fetch visual context for builds, comparisons, screenshots, and review queues. |
-| `vizzly upload <dir>` | Upload an existing folder of screenshots. |
-| `vizzly preview <dir>` | Upload static build output for in-context review. |
-| `vizzly approve <comparison-id>` | Approve a visual comparison. |
-| `vizzly reject <comparison-id>` | Reject a visual comparison with a reason. |
-| `vizzly comment <build-id>` | Add a build comment. |
-| `vizzly config [key]` | Inspect resolved configuration values. |
-| `vizzly login` | Authenticate through the browser. |
-| `vizzly doctor` | Validate your local setup. |
-
-## Documentation
-
-Full documentation lives at **[docs.vizzly.dev](https://docs.vizzly.dev)**.
-Start there for framework guides, CI setup, SDK examples, and the configuration
-reference.
-
-## Contributing
-
-Found a bug or have an idea?
-[Open an issue](https://github.com/vizzly-testing/cli/issues) or send a PR.
-
-## License
-
-MIT
+| `vizzly approve <comparison-id>` | Approve a comparison. |
+| `vizzly reject <comparison-id> --reason "message"` | Reject a comparison with a reason. |
+| `vizzly comment <build-id> "message"` | Comment on a build. |
+
+</details>
+
+<details>
+<summary>API</summary>
+
+| Command | What it does |
+| --- | --- |
+| `vizzly api schema [operation-id]` | Discover cloud API requests, fields, and response formats. |
+| `vizzly api <endpoint>` | Make API requests; use `--output <file>` for images. |
+
+</details>
+
+Installed plugins add commands such as `storybook`, `static-site`, and `previews`.
+See their setup guides above for details.
+
+## More
+
+[Full docs](https://docs.vizzly.dev) ·
+[Report a bug or suggest a change](https://github.com/vizzly-testing/cli/issues)
+
+PRs welcome. MIT licensed.

package/dist/cli.js

@@ -28,9 +28,7 @@ import { whoamiCommand } from './commands/whoami.js';
 import { createPluginServices } from './plugin-api.js';
 import { loadPlugins } from './plugin-loader.js';
 import { createServices } from './services/index.js';
-import { generateStaticReport, getReportFileUrl } from './services/static-report-generator.js';
 import { withTimeout } from './utils/async-utils.js';
-import { openBrowser } from './utils/browser.js';
 import { colors } from './utils/colors.js';
 import { loadConfig } from './utils/config-loader.js';
 import { getContext } from './utils/context.js';
@@ -430,38 +428,49 @@ output.configure({
   color: colorOverride,
   json: jsonArg
 });
-let config = await loadConfig(configPath, {
-  token: tokenArg
-});
-let services = createServices(config);
-let pluginServices = createPluginServices(services);
-let plugins = [];
-try {
-  plugins = await loadPlugins(configPath, config);
-  for (let plugin of plugins) {
-    try {
-      // Add timeout protection for plugin registration (5 seconds)
-      let registerPromise = plugin.register(program, {
-        config,
-        services: pluginServices,
-        output
-      });
-      await withTimeout(registerPromise, 5000, 'Plugin registration timeout (5s)');
-      output.debug(`Registered plugin: ${plugin.name}`);
-    } catch (error) {
-      output.warn(`Failed to register plugin ${plugin.name}: ${error.message}`);
+let setupCommand = findRequestedCommand(process.argv, new Set(['init', 'project']))?.name;
+let needsRuntimeBootstrap = !['init', 'project'].includes(setupCommand);
+if (needsRuntimeBootstrap) {
+  let config = await loadConfig(configPath, {
+    token: tokenArg
+  });
+  let services = createServices(config);
+  let pluginServices = createPluginServices(services);
+  try {
+    let plugins = await loadPlugins(configPath, config);
+    for (let plugin of plugins) {
+      try {
+        // Add timeout protection for plugin registration (5 seconds)
+        let registerPromise = plugin.register(program, {
+          config,
+          services: pluginServices,
+          output
+        });
+        await withTimeout(registerPromise, 5000, 'Plugin registration timeout (5s)');
+        output.debug(`Registered plugin: ${plugin.name}`);
+      } catch (error) {
+        output.warn(`Failed to register plugin ${plugin.name}: ${error.message}`);
+      }
     }
+  } catch (error) {
+    output.debug(`Plugin loading failed: ${error.message}`);
   }
-} catch (error) {
-  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 or refresh the repo-local Vizzly agent skill').option('--agent-guidance', 'Install or refresh the repo-local Vizzly skill and AGENTS.md guidance').option('--skip-agent-skill', 'Skip the Vizzly agent skill prompt').action(async options => {
+program.command('init').description('Initialize Vizzly in your project').option('--quick', 'Create an editable config without the setup wizard').option('--force', 'Overwrite existing configuration').option('--agent-skill', 'Install the Vizzly agent skill during setup').option('--agent-guidance', 'Install the Vizzly skill and AGENTS.md guidance during setup').option('--skip-agent-skill', 'Skip the Vizzly agent skill prompt').action(async options => {
   let globalOptions = getGlobalOptions();
-  await init({
-    ...globalOptions,
-    ...options,
-    plugins
-  });
+  try {
+    let result = await init({
+      ...globalOptions,
+      ...options
+    });
+    process.exitCode = result.exitCode || 0;
+  } catch (error) {
+    output.error(error.message, error, {
+      changes: error.completed || []
+    });
+    if (error.completed?.length) output.list(error.completed.map(change => change.path));
+    process.exitCode = error.code === 'INIT_INPUT_REQUIRED' ? 2 : 1;
+  }
 });
 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();
@@ -555,7 +564,10 @@ tddCmd.command('run <command>').description('Run tests once in TDD mode with loc
   const {
     result,
     cleanup
-  } = await tddCommand(command, options, globalOptions);
+  } = await tddCommand(command, {
+    ...options,
+    autoPort: options.port === undefined
+  }, globalOptions);
 
   // Track cleanup state to prevent double cleanup
   let isCleaningUp = false;
@@ -575,26 +587,6 @@ tddCmd.command('run <command>').description('Run tests once in TDD mode with loc
   process.once('SIGINT', sigintHandler);
   process.once('SIGTERM', sigtermHandler);
 
-  // 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.
-    const reportResult = await generateStaticReport(process.cwd());
-    if (reportResult.success) {
-      const reportUrl = getReportFileUrl(reportResult.reportPath);
-      output.print(`  ${colors.brand.textTertiary('→')} Report: ${colors.info(reportUrl)}`);
-      output.blank();
-
-      // Open report in browser unless --no-open
-      if (options.open !== false) {
-        await openBrowser(reportUrl);
-      }
-    } else {
-      output.warn(`Failed to generate static report: ${reportResult.error}`);
-    }
-  }
-
   // Remove signal handlers before normal cleanup to prevent double cleanup
   process.off('SIGINT', sigintHandler);
   process.off('SIGTERM', sigtermHandler);
@@ -950,7 +942,7 @@ program.command('whoami').description('Show current authentication status and us
 
 // Save PATH for the menubar app before commands read or update credentials
 // in the same config file.
-await saveUserPath().catch(() => {});
+if (needsRuntimeBootstrap) await 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.registeredArguments.length ? [] : command.commands.map(subcommand => subcommand.name()))]));
 let normalizedArgv = normalizeJsonArgv(process.argv, commandNames);
@@ -971,7 +963,7 @@ if (requestedCommand && !requestedCommand.known) {
   process.exit(1);
 }
 try {
-  program.parse(normalizedArgv);
+  await program.parseAsync(normalizedArgv);
 } catch (error) {
   if (error.exitCode == null) {
     output.error('Unexpected CLI error', error);