@vizzly-testing/cli 0.38.0 → 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,259 +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+.
+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';
 
-### Start Local TDD
+test('homepage looks correct', async ({ page }) => {
+  await page.goto('/');
+  await vizzlyScreenshot('homepage', await page.screenshot());
+});
+```
 
-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`.
+The client runs in Node.js and works with any Node-based test runner. You can
+also pass a file path:
 
-```bash
-vizzly tdd start --open
-pnpm test -- --watch
+```javascript
+await vizzlyScreenshot('homepage', './screenshots/homepage.png');
 ```
 
-The dashboard shows screenshots, baselines, and diffs as they arrive. Accept or
-reject changes right from the UI.
+### Review locally
 
-For a one-off local check, wrap the test command with `tdd run`:
+Start the local TDD server, then run your tests in another terminal:
 
 ```bash
-vizzly tdd run "pnpm test" --no-open
-vizzly context build current --source local --json
+pnpm exec vizzly tdd start --open
+pnpm test -- --watch # Replace this with your test command
 ```
 
-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.
+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>`.
 
-### Run With Cloud Review
-
-Use cloud builds when you want shared baselines, team review, and CI status:
+For a single run:
 
 ```bash
-vizzly login
-vizzly project link your-org/your-project
-vizzly run "pnpm test" --wait
+pnpm exec vizzly tdd run "pnpm test" --no-open
 ```
 
-`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.
-
-`--wait` blocks until Vizzly finishes processing the build. It exits with code
-`1` when visual differences need review.
+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.
 
-In CI, use a project token:
+### Review in the cloud
 
 ```bash
-export VIZZLY_TOKEN=your-project-token
-vizzly run "pnpm test" --wait
+pnpm exec vizzly login
+pnpm exec vizzly project link your-org/your-project
+pnpm exec vizzly run "pnpm test"
 ```
 
-### 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:
+`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.
 
-```bash
-vizzly api schema --json
-vizzly api schema sdk.listBuilds --json
-```
+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.
 
-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.
+To upload screenshots you already have:
 
 ```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
+pnpm exec vizzly upload ./screenshots
 ```
 
-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.
+### Run in CI
 
-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.
+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:
 
-The `context` commands are read-only. The schema-discovered review API also
-supports explicit decisions when a task asks for them.
+```bash
+export VIZZLY_TOKEN=your-project-token
+pnpm exec vizzly run "pnpm test" --wait
+```
 
-## Capture Screenshots
+With `--wait`, failed comparisons make the command exit with code `1`.
 
-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 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 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 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/auth/client.js

@@ -56,7 +56,10 @@ export function createAuthClient(options = {}) {
     });
     if (!response.ok) {
       let body = await parseResponseBody(response);
-      throw parseAuthError(response.status, body, endpoint);
+      let error = parseAuthError(response.status, body, endpoint);
+      let retryAfter = Number(response.headers?.get('retry-after'));
+      if (retryAfter > 0) error.context.retryAfter = retryAfter;
+      throw error;
     }
     return response.json();
   }

package/dist/auth/core.js

@@ -70,13 +70,19 @@ export function parseAuthError(status, body, _endpoint) {
   } else if (typeof body === 'string') {
     errorText = body;
   }
+  let retryAfter = Number(body?.retryAfter);
+  let context = {
+    status,
+    serverCode: body?.code,
+    retryAfter: retryAfter > 0 ? retryAfter : undefined
+  };
   if (status === 401) {
-    return new AuthError(errorText || 'Invalid credentials. Please check your email/username and password.');
+    return new AuthError(errorText || 'Invalid credentials. Please check your email/username and password.', context);
   }
   if (status === 429) {
-    return new VizzlyError('Too many login attempts. Please try again later.', 'RATE_LIMIT_ERROR');
+    return new VizzlyError('Too many login attempts. Please try again later.', 'RATE_LIMIT_ERROR', context);
   }
-  return new VizzlyError(`Authentication request failed: ${status}${errorText ? ` - ${errorText}` : ''}`, 'AUTH_REQUEST_ERROR');
+  return new VizzlyError(`Authentication request failed: ${status}${errorText ? ` - ${errorText}` : ''}`, 'AUTH_REQUEST_ERROR', context);
 }
 
 /**
@@ -173,4 +179,59 @@ export function validateTokens(auth, requiredField = 'accessToken') {
     valid: true,
     error: null
   };
+}
+export function normalizeDeviceFlowResponse(deviceFlow) {
+  let verificationUri = deviceFlow.verification_uri || deviceFlow.verificationUri;
+  let userCode = deviceFlow.user_code || deviceFlow.userCode;
+  let deviceCode = deviceFlow.device_code || deviceFlow.deviceCode;
+  if (!verificationUri || !userCode || !deviceCode) {
+    throw new Error('Invalid device flow response from server');
+  }
+  return {
+    verificationUri,
+    userCode,
+    deviceCode,
+    urlWithCode: deviceFlow.verification_uri_complete || deviceFlow.verificationUriComplete || `${verificationUri}?code=${encodeURIComponent(userCode)}`
+  };
+}
+export function resolveAuthorizedTokenData(pollResponse) {
+  let accessToken = pollResponse.tokens?.accessToken || pollResponse.tokens?.access_token;
+  if (accessToken) {
+    return pollResponse;
+  }
+  if (pollResponse.status === 'pending') {
+    throw new Error('Authorization not complete yet. Please complete the authorization in your browser and try running "vizzly login" again.');
+  }
+  if (pollResponse.status === 'expired') {
+    throw new Error('Device code expired. Please try logging in again.');
+  }
+  if (pollResponse.status === 'invalid') {
+    throw new Error('Device code is invalid or expired. Please try logging in again.');
+  }
+  if (pollResponse.status === 'denied') {
+    throw new Error('Authorization denied. Please try logging in again.');
+  }
+  throw new Error('Unexpected response from authorization server. Please try logging in again.');
+}
+export function buildTokens(tokenData, now = Date.now()) {
+  let tokensData = tokenData.tokens || tokenData;
+  let tokenExpiresIn = tokensData.expiresIn || tokensData.expires_in;
+  let tokenExpiresAt = tokenExpiresIn ? new Date(now + tokenExpiresIn * 1000).toISOString() : tokenData.expires_at || tokenData.expiresAt;
+  return {
+    accessToken: tokensData.accessToken || tokensData.access_token,
+    refreshToken: tokensData.refreshToken || tokensData.refresh_token,
+    expiresAt: tokenExpiresAt,
+    user: tokenData.user,
+    organizations: tokenData.organizations
+  };
+}
+
+/** Map protocol codes without depending on the server's human-readable text. */
+export function deviceAuthorizationStatus(error) {
+  return {
+    AUTHORIZATION_PENDING: 'pending',
+    ACCESS_DENIED: 'denied',
+    EXPIRED_TOKEN: 'expired',
+    INVALID_DEVICE_CODE: 'invalid'
+  }[error.context?.serverCode];
 }

package/dist/auth/operations.js

@@ -8,7 +8,8 @@
  * This makes them trivially testable without mocking modules.
  */
 
-import { buildDevicePollPayload, buildLogoutPayload, buildRefreshPayload, buildTokenData, validateTokens } from './core.js';
+import * as output from '../utils/output.js';
+import { buildDevicePollPayload, buildLogoutPayload, buildRefreshPayload, buildTokenData, deviceAuthorizationStatus, validateTokens } from './core.js';
 
 // ============================================================================
 // Device Flow Operations
@@ -34,14 +35,23 @@ export async function initiateDeviceFlow(httpClient) {
  * @param {string} deviceCode - Device code from initiate
  * @returns {Promise<Object>} Token data or pending status
  */
-export async function pollDeviceAuthorization(httpClient, deviceCode) {
-  return httpClient.request('/api/auth/cli/device/poll', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify(buildDevicePollPayload(deviceCode))
-  });
+export async function pollDeviceAuthorization(httpClient, deviceCode, options = {}) {
+  try {
+    return await httpClient.request('/api/auth/cli/device/poll', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(buildDevicePollPayload(deviceCode)),
+      signal: options.signal
+    });
+  } catch (error) {
+    let status = deviceAuthorizationStatus(error);
+    if (status) return {
+      status
+    };
+    throw error;
+  }
 }
 
 /**
@@ -98,7 +108,7 @@ export async function logout(httpClient, tokenStore) {
   let auth = await tokenStore.getTokens();
   if (auth?.refreshToken) {
     try {
-      await httpClient.request('/api/auth/cli/logout', {
+      await httpClient.authenticatedRequest('/api/auth/cli/logout', auth.accessToken, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json'
@@ -107,7 +117,7 @@ export async function logout(httpClient, tokenStore) {
       });
     } catch (error) {
       // If server request fails, still clear local tokens
-      console.warn('Warning: Failed to revoke tokens on server:', error.message);
+      output.warn(`Failed to revoke tokens on server: ${error.message}`);
     }
   }
   await tokenStore.clearTokens();