@vizzly-testing/cli 0.35.3-beta.4 → 0.37.0

package/README.md

@@ -62,7 +62,7 @@ For a one-off local check, wrap the test command with `tdd run`:
 
 ```bash
 vizzly tdd run "pnpm test" --no-open
-vizzly context build current --source local --agent
+vizzly context build current --source local --json
 ```
 
 That run writes review data under `.vizzly/` and prints a context command you
@@ -96,38 +96,44 @@ vizzly run "pnpm test" --wait
 
 ### Inspect Builds And Diffs
 
-Use `vizzly context` when you need build, comparison, screenshot, or review
-queue data from the terminal.
+Use `vizzly context` for human summaries and local `.vizzly` evidence. For cloud
+reviews, agents should discover and call the public API through its schema:
 
-This is useful for scripts, coding agents, and debugging loops. Instead of
-making a pile of narrow API calls, ask for one focused bundle and get the
-evidence in one place.
+```bash
+vizzly api schema --json
+vizzly api schema sdk.listBuilds --json
+```
+
+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.
 
 ```bash
-# Cloud context for a build or comparison
+# Human-readable cloud build context
 vizzly context build abc123 --source cloud
-vizzly context comparison def456 --source cloud --agent --json
+
+# 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 --agent
+vizzly context build current --source local --json
 vizzly context screenshot build-detail-screenshots --source local --json
 vizzly context review-queue --source local --json
 ```
 
-`--json` is the durable automation path. `--agent` gives you the compact API
-handoff for prompt assembly. Build handoffs contain up to 10 records; use the
-exact next-page command returned in `suggested_commands` to continue safely.
-That command carries the API's opaque `--cursor`. Add
-`--include diffs` for raw diff diagnostics, or `--full` when you need the whole
-payload.
+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.
 
-Cloud context is also read-only right now. That is intentional. Vizzly helps you
-see and inspect visual changes, while people still decide what gets approved.
+The `context` commands are read-only. The schema-discovered review API also
+supports explicit decisions when a task asks for them.
 
 ## Capture Screenshots
 
@@ -144,18 +150,19 @@ test('homepage looks correct', async ({ page }) => {
     fullPage: true,
     requestTimeout: 5000,
     properties: {
-      browser: 'chrome',
-      viewport: { width: 1920, height: 1080 },
+      theme: 'dark',
+      locale: 'en-US',
     },
   });
 });
 ```
 
-`properties` is your metadata bag for baseline grouping, filtering, and
-debugging. SDK options such as `threshold`, `minClusterSize`, `fullPage`,
-`requestTimeout`, and `buildId` stay at the top level. Reserved SDK and capture
-fields inside `properties` are ignored and produce a warning; they are never
-interpreted as options or stored as user metadata.
+`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
+`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.

package/dist/api/client.js

@@ -56,6 +56,11 @@ export function createApiClient(options = {}) {
    * @returns {Promise<Object>} Parsed JSON response
    */
   async function request(endpoint, fetchOptions = {}, isRetry = false) {
+    let {
+      responseType = 'json',
+      retryAuthentication = true,
+      ...httpOptions
+    } = fetchOptions;
     let url = buildApiUrl(baseUrl, endpoint);
     let headers = buildRequestHeaders({
       token,
@@ -66,7 +71,7 @@ export function createApiClient(options = {}) {
     let response;
     try {
       response = await fetch(url, {
-        ...fetchOptions,
+        ...httpOptions,
         headers
       });
     } catch (error) {
@@ -80,7 +85,7 @@ export function createApiClient(options = {}) {
       let errorBody = await extractErrorBody(response);
 
       // Handle 401 with token refresh
-      if (shouldRetryWithRefresh(response.status, isRetry, !isProjectToken(token) && (await hasRefreshToken()))) {
+      if (retryAuthentication && shouldRetryWithRefresh(response.status, isRetry, !isProjectToken(token) && (await hasRefreshToken()))) {
         let refreshed = await attemptTokenRefresh();
         if (refreshed) {
           token = refreshed;
@@ -100,6 +105,12 @@ export function createApiClient(options = {}) {
         details: error.details
       });
     }
+    if (responseType === 'response') return response;
+    if (response.status === 204 || httpOptions.method === 'HEAD') return null;
+    let contentType = response.headers?.get?.('content-type');
+    if (contentType && !/application\/(?:[\w.+-]+\+)?json\b/i.test(contentType)) {
+      throw new VizzlyError('This response contains file data. Use api --output <file> to download it.', 'BINARY_RESPONSE');
+    }
     return response.json();
   }
 
@@ -122,6 +133,7 @@ export function createApiClient(options = {}) {
       let refreshUrl = buildApiUrl(baseUrl, '/api/auth/cli/refresh');
       let response = await fetch(refreshUrl, {
         method: 'POST',
+        redirect: 'error',
         headers: {
           'Content-Type': 'application/json',
           'User-Agent': userAgent

package/dist/api/core.js

@@ -30,14 +30,17 @@ export function buildAuthHeader(token) {
  * @param {string} version - CLI version
  * @param {string} command - Command being executed (run, upload, tdd, etc.)
  * @param {string|null} sdkUserAgent - Optional SDK user agent to append
+ * @param {string} nodeVersion - Node.js version to append
  * @returns {string} Complete User-Agent string
  */
-export function buildUserAgent(version, command, sdkUserAgent = null) {
+export function buildUserAgent(version, command, sdkUserAgent = null, nodeVersion = process.versions.node) {
   let baseUserAgent = `vizzly-cli/${version} (${command})`;
+  let userAgentParts = [baseUserAgent];
   if (sdkUserAgent) {
-    return `${baseUserAgent} ${sdkUserAgent}`;
+    userAgentParts.push(sdkUserAgent);
   }
-  return baseUserAgent;
+  if (nodeVersion) userAgentParts.push(`node/${nodeVersion}`);
+  return userAgentParts.join(' ');
 }
 
 /**
@@ -74,7 +77,7 @@ export function buildRequestHeaders({
  * Build payload for screenshot upload or SHA resolution
  * @param {string} name - Screenshot name
  * @param {Buffer|null} buffer - Image data, or null when resolving by SHA
- * @param {Object} metadata - Screenshot metadata (viewport, browser, etc.)
+ * @param {Object} metadata - User screenshot properties
  * @param {string|null} sha256 - Pre-computed SHA256 hash (optional)
  * @returns {Object} Screenshot upload payload
  */
@@ -98,7 +101,7 @@ export function buildScreenshotPayload(name, buffer, metadata = {}, sha256 = nul
 /**
  * Build payload for server-side screenshot resolution without sending image bytes
  * @param {string} name - Screenshot name
- * @param {Object} metadata - Screenshot metadata (viewport, browser, etc.)
+ * @param {Object} metadata - User screenshot properties
  * @param {string} sha256 - Pre-computed SHA256 hash
  * @returns {Object} Screenshot resolution payload
  */
@@ -190,9 +193,6 @@ export function buildScreenshotCheckObject(sha256, name, metadata = {}) {
   return {
     sha256,
     name,
-    browser: meta.browser || 'chrome',
-    viewport_width: meta.viewport?.width || meta.viewport_width || 1920,
-    viewport_height: meta.viewport?.height || meta.viewport_height || 1080,
     properties
   };
 }

package/dist/api/endpoints.js

@@ -80,13 +80,15 @@ export async function createBuild(client, metadata) {
  * @param {Object} client - API client
  * @param {string} buildId - Build ID
  * @param {string} status - Build status (pending|running|completed|failed)
- * @param {number|null} executionTimeMs - Execution time in milliseconds
+ * @param {number|null} [executionTimeMs=null] - Execution time in milliseconds
+ * @param {string} [failureReason] - Explanation sent only for a failed build
  * @returns {Promise<Object>} Updated build data
  */
-export async function updateBuildStatus(client, buildId, status, executionTimeMs = null) {
+export async function updateBuildStatus(client, buildId, status, executionTimeMs = null, failureReason) {
   let body = {
     status
   };
+  if (status === 'failed' && failureReason) body.failureReason = failureReason;
   if (executionTimeMs != null) {
     body.executionTimeMs = executionTimeMs;
   }
@@ -100,16 +102,17 @@ export async function updateBuildStatus(client, buildId, status, executionTimeMs
 }
 
 /**
- * Finalize a build (convenience wrapper for updateBuildStatus)
+ * Mark a build completed or failed, with an optional failure explanation.
  * @param {Object} client - API client
  * @param {string} buildId - Build ID
- * @param {boolean} success - Whether the build succeeded
- * @param {number|null} executionTimeMs - Execution time in milliseconds
+ * @param {boolean} [success=true] - Whether tests and uploads succeeded
+ * @param {number|null} [executionTimeMs=null] - Execution time in milliseconds
+ * @param {string} [failureReason] - Explanation sent only for a failed build
  * @returns {Promise<Object>} Finalized build data
  */
-export async function finalizeBuild(client, buildId, success = true, executionTimeMs = null) {
+export async function finalizeBuild(client, buildId, success = true, executionTimeMs = null, failureReason) {
   let status = success ? 'completed' : 'failed';
-  return updateBuildStatus(client, buildId, status, executionTimeMs);
+  return updateBuildStatus(client, buildId, status, executionTimeMs, failureReason);
 }
 
 /**

package/dist/cli.js

@@ -2,7 +2,7 @@
 import 'dotenv/config';
 import { existsSync, statSync } from 'node:fs';
 import { Option, program } from 'commander';
-import { apiCommand, validateApiOptions } from './commands/api.js';
+import { apiCommand, apiSchemaCommand, validateApiOptions } from './commands/api.js';
 import { baselinesCommand } from './commands/baselines.js';
 import { buildsCommand, validateBuildsOptions } from './commands/builds.js';
 import { comparisonsCommand, validateComparisonsOptions } from './commands/comparisons.js';
@@ -357,6 +357,10 @@ function getGlobalOptions() {
     noColor: options.noColor || options.color === false
   };
 }
+function warnDeprecatedContextAgentOption() {
+  let warning = ['`vizzly context --agent` is deprecated and will be removed in v0.38.0.', 'For cloud reviews, use `vizzly api schema --json` and follow the', 'discovered operations. For local evidence, use', '`vizzly context ... --json`.'].join(' ');
+  output.warn(warning);
+}
 function reportValidationErrors(errors) {
   if (output.isJson()) {
     output.error('Validation errors', null, {
@@ -651,30 +655,38 @@ Examples:
   await comparisonsCommand(options, globalOptions);
 });
 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 instead of compact context').option('--cursor <cursor>', 'Continue compact evidence from an opaque API cursor').option('--include <items>', 'Add raw diff diagnostics to compact context: diffs').addHelpText('after', `
+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', 'Deprecated; use API schema for cloud review.').option('--full', 'Return the full build context instead of compact context').option('--cursor <cursor>', 'Continue compact evidence from an opaque API cursor').option('--include <items>', 'Add raw diff diagnostics to compact context: diffs').addHelpText('after', `
 Examples:
   $ vizzly context build abc123 --source cloud
   $ vizzly context build current --source local
-  $ vizzly context build current --source local --agent
-  $ vizzly context build abc123 --source cloud --agent --json
-  $ vizzly context build abc123 --source cloud --agent --json --include diffs
-  $ vizzly context build abc123 --source cloud --agent --json --full
+  $ vizzly api schema --json
+  $ vizzly context build current --source local --json
+
+Deprecation:
+  --agent will be removed in v0.38.0. Use the API schema for cloud reviews;
+  use --json without --agent for local evidence.
 `).action(async (buildId, options) => {
   let globalOptions = getGlobalOptions();
+  if (options.agent) warnDeprecatedContextAgentOption();
   const validationErrors = validateContextBuildOptions(options);
   if (validationErrors.length > 0) {
     reportValidationErrors(validationErrors);
   }
   await contextBuildCommand(buildId, options, globalOptions);
 });
-contextCmd.command('comparison').description('Fetch a comparison context bundle').argument('<comparison-id>', 'Comparison 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 comparison context instead of compact context').option('--cursor <cursor>', 'Continue compact history from an opaque API cursor').option('--include <items>', 'Add detail to compact context: diffs').addHelpText('after', `
+contextCmd.command('comparison').description('Fetch a comparison context bundle').argument('<comparison-id>', 'Comparison ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('--agent', 'Deprecated; use API schema for cloud review.').option('--full', 'Return the full comparison context instead of compact context').option('--cursor <cursor>', 'Continue compact history from an opaque API cursor').option('--include <items>', 'Add detail to compact context: diffs').addHelpText('after', `
 Examples:
   $ vizzly context comparison def456 --source cloud
   $ vizzly context comparison def456 --source local
   $ vizzly context comparison def456 --source cloud --json
-  $ vizzly context comparison def456 --source cloud --agent --json
+  $ vizzly api schema getComparisonContext --json
+
+Deprecation:
+  --agent will be removed in v0.38.0. Use the API schema for cloud reviews;
+  use --json without --agent for local evidence.
 `).action(async (comparisonId, options) => {
   let globalOptions = getGlobalOptions();
+  if (options.agent) warnDeprecatedContextAgentOption();
   const validationErrors = validateContextComparisonOptions(options);
   if (validationErrors.length > 0) {
     reportValidationErrors(validationErrors);
@@ -738,7 +750,7 @@ Note: Baselines are stored locally in .vizzly/baselines/ during TDD mode.
   let globalOptions = getGlobalOptions();
   await baselinesCommand(options, globalOptions);
 });
-program.command('api').description('Make raw API requests (for power users)').argument('<endpoint>', 'API endpoint (e.g., /api/sdk/builds)').option('-X, --method <method>', 'HTTP method (GET or POST for build comments)', 'GET').option('-d, --data <json>', 'Request body (JSON)').option('-H, --header <header>', 'Add header (key:value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).option('-q, --query <param>', 'Add query param (key=value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).addHelpText('after', `
+let api = program.command('api').description('Make raw API requests (for power users)').argument('<endpoint>', 'API endpoint (e.g., /api/sdk/builds)').option('-X, --method <method>', 'HTTP method; discover supported requests with api schema', 'GET').option('-d, --data <json>', 'JSON body, @file, or @- for stdin').option('-o, --output <file>', 'Write response bytes to a new file').option('-H, --header <header>', 'Add header (key:value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).option('-q, --query <param>', 'Add query param (key=value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).addHelpText('after', `
 Examples:
   $ vizzly api /api/sdk/builds                    # List builds
   $ vizzly api /api/sdk/builds -q limit=5         # With query params
@@ -746,8 +758,10 @@ Examples:
   $ vizzly api /api/sdk/builds/abc123/comments -X POST -d '{"content":"Looks good"}'
   $ vizzly api /api/sdk/builds/abc123/comments -X POST -d '{"content":"Nice!"}'
 
-Note: POST is restricted to build comment endpoints. Use dedicated approve/reject commands for review decisions.
-Most operations have dedicated commands (builds, comparisons, approve, etc.).
+Discover operations: vizzly api schema, then vizzly api schema <operation-id>.
+Use the method, version header, parameters and body described there.
+JSON output places the API payload under data.response. Image downloads use --output.
+Writes are never automatically retried after authentication failures.
 `).action(async (endpoint, options) => {
   let globalOptions = getGlobalOptions();
 
@@ -758,6 +772,17 @@ Most operations have dedicated commands (builds, comparisons, approve, etc.).
   }
   await apiCommand(endpoint, options, globalOptions);
 });
+api.command('schema [operation-id]').description('Discover supported API operations and their request/response schemas').option('--full', 'Download full OpenAPI (requires --output)').option('-q, --query <param>', 'Schema view=request, fields, response, or full', (value, previous) => [...(previous || []), value]).option('-o, --output <file>', 'Write the schema to a new file').action(async (operationId, options) => {
+  options = {
+    ...api.opts(),
+    ...options
+  };
+  if (options.full && !options.output) {
+    reportValidationErrors(['--full requires --output to avoid dumping the entire schema.']);
+    return;
+  }
+  await apiSchemaCommand(operationId, options, getGlobalOptions());
+});
 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
@@ -909,11 +934,11 @@ program.command('whoami').description('Show current authentication status and us
   await whoamiCommand(options, globalOptions);
 });
 
-// Save user's PATH for menubar app (non-blocking, runs in background)
-// This auto-configures the menubar app so it can find package runners/node
-saveUserPath().catch(() => {});
+// Save PATH for the menubar app before commands read or update credentials
+// in the same config file.
+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.commands.map(subcommand => subcommand.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);
 let normalizedGlobals = extractGlobalOptionsFromArgv(normalizedArgv, commandNames);
 output.configure({

package/dist/client/index.js

@@ -203,9 +203,6 @@ function createSimpleClient(serverUrl, clientOptions = {}) {
     async screenshot(name, imageBuffer, options = {}) {
       let normalizedOptions = normalizeScreenshotOptions(options);
       let requestTimeout = normalizedOptions.requestTimeout || DEFAULT_TIMEOUT_MS;
-      for (let warning of normalizedOptions.warnings) {
-        console.warn(`[vizzly] ${warning.message}`);
-      }
       try {
         // If it's a string, assume it's a file path and send directly
         // Otherwise it's a Buffer, so convert to base64
@@ -220,9 +217,6 @@ function createSimpleClient(serverUrl, clientOptions = {}) {
           properties: normalizedOptions.properties
         };
         Object.assign(screenshotData, getScreenshotOptionsPayload(normalizedOptions));
-        if (normalizedOptions.warnings.length > 0) {
-          screenshotData.warnings = normalizedOptions.warnings;
-        }
         let httpStart = Date.now();
         let {
           status,

package/dist/commands/api.js

@@ -2,10 +2,14 @@
  * API command - raw API access for power users
  */
 
+import { open, readFile, unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 import { createApiClient as defaultCreateApiClient } from '../api/index.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import * as defaultOutput from '../utils/output.js';
-let ALLOWED_POST_ENDPOINTS = [/^\/api\/sdk\/builds\/[^/]+\/comments$/];
+let API_METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'];
 function createApiCommandDeps(deps = {}) {
   return {
     loadConfig: deps.loadConfig || defaultLoadConfig,
@@ -31,9 +35,6 @@ export function normalizeApiEndpoint(endpoint) {
 export function normalizeApiMethod(method = 'GET') {
   return method.toUpperCase();
 }
-export function isAllowedPostEndpoint(endpoint) {
-  return ALLOWED_POST_ENDPOINTS.some(pattern => pattern.test(endpoint));
-}
 export function parseApiHeaders(headerOption) {
   let headers = {};
   let headerList = Array.isArray(headerOption) ? headerOption : [headerOption];
@@ -69,15 +70,14 @@ export function validateApiRequest({
   hasData = false
 }) {
   let errors = [];
-  if (method !== 'GET' && method !== 'POST') {
-    errors.push(`Method ${method} not allowed. Use GET for queries or POST for build comments.`);
-    return errors;
+  if (!API_METHODS.includes(method)) {
+    errors.push(`Unsupported HTTP method: ${method}`);
   }
-  if (method === 'POST' && !isAllowedPostEndpoint(endpoint)) {
-    errors.push(`POST not allowed for ${endpoint}. Only build comment endpoints support POST.`);
+  if (hasData && ['GET', 'HEAD'].includes(method)) {
+    errors.push('Request data requires a method other than GET or HEAD.');
   }
-  if (hasData && method !== 'POST') {
-    errors.push('Request data requires --method POST.');
+  if (/^[a-z][a-z\d+.-]*:/i.test(endpoint) || endpoint.startsWith('//')) {
+    errors.push('Use an API path on the configured Vizzly server.');
   }
   return errors;
 }
@@ -88,7 +88,7 @@ export function buildApiRequest({
   let normalizedEndpoint = normalizeApiEndpoint(endpoint);
   let method = normalizeApiMethod(options.method || 'GET');
   let errors = validateApiRequest({
-    endpoint: normalizedEndpoint,
+    endpoint,
     method,
     hasData: options.data !== undefined
   });
@@ -104,7 +104,7 @@ export function buildApiRequest({
   let requestOptions = {
     method
   };
-  if (options.data && method === 'POST') {
+  if (options.data !== undefined && !['GET', 'HEAD'].includes(method)) {
     headers['Content-Type'] = headers['Content-Type'] || 'application/json';
     requestOptions.body = options.data;
   }
@@ -144,13 +144,24 @@ export async function apiCommand(endpoint, options = {}, globalOptions = {}, dep
     };
     let config = await loadConfig(globalOptions.config, allOptions);
 
-    // Validate API token
-    if (!config.apiKey) {
-      output.error('API token required. Use --token or set VIZZLY_TOKEN environment variable');
+    // A linked project's upload credential must not hide an existing user login.
+    // Explicit file/env/--token credentials still take precedence.
+    let token = config.linkedProject ? config.userToken || config.apiKey : config.apiKey || config.userToken;
+    if (!token && !options.schemaDiscovery) {
+      output.error('Authentication required. Run vizzly login or set VIZZLY_TOKEN.');
       output.cleanup();
       exit(1);
       return;
     }
+    if (options.data?.startsWith('@')) {
+      let source = options.data.slice(1);
+      let data = source === '-' ? await readStdin() : await readFile(source, 'utf8');
+      options = {
+        ...options,
+        data
+      };
+    }
+    if (options.data !== undefined) JSON.parse(options.data);
     let {
       errors,
       method,
@@ -164,10 +175,7 @@ export async function apiCommand(endpoint, options = {}, globalOptions = {}, dep
     displayMethod = method;
     if (errors.length > 0) {
       output.error(errors[0]);
-      if (method === 'POST') {
-        output.hint('Use GET for queries, or use dedicated commands (vizzly approve, vizzly reject, vizzly comment)');
-      }
-      output.hint('Most raw API use should stay read-only; prefer dedicated commands for mutations.');
+      output.hint('Use vizzly api schema to discover supported operations.');
       output.cleanup();
       exit(1);
       return;
@@ -177,10 +185,31 @@ export async function apiCommand(endpoint, options = {}, globalOptions = {}, dep
     output.startSpinner(`${method} ${normalizedEndpoint}`);
     let client = createApiClient({
       baseUrl: config.apiUrl,
-      token: config.apiKey,
-      command: 'api'
+      token,
+      command: 'api',
+      allowNoToken: Boolean(options.schemaDiscovery)
+    });
+    let response = await client.request(normalizedEndpoint, {
+      ...requestOptions,
+      redirect: 'error',
+      retryAuthentication: ['GET', 'HEAD'].includes(method),
+      responseType: options.output ? 'response' : 'json'
     });
-    let response = await client.request(normalizedEndpoint, requestOptions);
+    if (options.output) {
+      let path = resolve(options.output);
+      let file = await open(path, 'wx');
+      try {
+        await pipeline(response.body || Readable.from([]), file.createWriteStream());
+      } catch (error) {
+        await file.close();
+        await unlink(path);
+        throw error;
+      }
+      response = {
+        file: path,
+        contentType: response.headers.get('content-type')
+      };
+    }
     output.stopSpinner();
 
     // Output response
@@ -240,12 +269,30 @@ export function validateApiOptions(endpoint, options = {}) {
   if (!endpoint || endpoint.trim() === '') {
     return errors;
   }
-  let normalizedEndpoint = normalizeApiEndpoint(endpoint);
   let method = normalizeApiMethod(options.method || 'GET');
   errors.push(...validateApiRequest({
-    endpoint: normalizedEndpoint,
+    endpoint,
     method,
     hasData: options.data !== undefined
   }));
   return errors;
+}
+async function readStdin() {
+  let chunks = [];
+  for await (let chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks.map(chunk => Buffer.from(chunk))).toString('utf8');
+}
+export async function apiSchemaCommand(operationId, options, globalOptions) {
+  let endpoint = '/api/sdk/schema';
+  if (operationId) {
+    endpoint += `/${encodeURIComponent(operationId)}`;
+    if (options.full) options = {
+      ...options,
+      query: [...(options.query || []), 'view=full']
+    };
+  } else if (options.full) endpoint += '/openapi';
+  return apiCommand(endpoint, {
+    ...options,
+    schemaDiscovery: true
+  }, globalOptions);
 }

package/dist/commands/init.js

@@ -223,8 +223,10 @@ For user-facing changes, use the repo-local Vizzly skill at
 
 - Inspect existing visual evidence before and after the change.
 - Use the repository's established Vizzly command and owning user workflow.
-- Read bounded JSON with \`--agent --json\`, then inspect baseline, current, and
-  diff images together.
+- For cloud reviews, discover supported requests with
+  \`vizzly api schema --json\` and inspect baseline, current, and diff images
+  together.
+- For local evidence, use \`vizzly context ... --json\`.
 
 Treat Vizzly diffs as review evidence. Do not approve, reject, or replace
 evidence unless the task explicitly asks for that mutation.