specshield 3.2.4 → 3.2.6

package/README.md

@@ -5,13 +5,40 @@
 [![license](https://img.shields.io/badge/license-MIT-blue)](#license)
 [![node](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org)
 
+## Contents
+
+**Get started**
+- [Quick Start](#quick-start) · [`specshield init` wizard](#specshield-init--first-run-setup-wizard) · [Login & Authentication](#login--authentication)
+
+**Why SpecShield**
+- [The Problem](#the-problem) · [The Solution](#the-solution) · [See It in Action](#see-it-in-action) · [Use Cases](#use-cases)
+- [Local vs Cloud](#local-vs-cloud) · [vs. Alternatives](#vs-alternatives) · [Pricing](#pricing)
+
+**Commands — local & hosted compare**
+- [Local Compare](#local-compare) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
+
+**Bi-Directional Contract Testing (BDCT)**
+- [BDCT overview & full command reference](#bi-directional-contract-testing-bdct)
+- [`bdct capture from-har` — HAR → consumer contract](#bdct-capture-from-har--turn-real-traffic-into-a-consumer-contract)
+  - [Step 1 — record a HAR](#step-1--record-a-har-file) · [Step 2 — generate contract](#step-2--turn-the-har-into-a-consumer-contract) · [Step 3 — publish + gate](#step-3--publish--gate) · [Operational concerns](#operational-concerns-read-this-before-going-live)
+- [`bdct verify-provider` — spec-vs-production conformance](#bdct-verify-provider--does-your-live-provider-actually-match-its-spec)
+
+**CI/CD**
+- [GitHub Actions workflows](#cicd--github-actions)
+
+**Reference**
+- [Config File](#config-file) · [All Options](#all-options) · [Exit Codes](#exit-codes)
+
+**Project**
+- [License](#license) · [Support](#support)
+
 ---
 
 > **OpenAPI Diff · Breaking-Change Detection · Bi-Directional Contract Testing · `can-i-deploy` Gate · Pact-File Ingest · Live-Traffic Capture · Spec-vs-Production Conformance · GitHub PR Checks**
 
 ---
 
-## Never ship a breaking change to your API consumers.
+## Never ship a breaking change to your API consumers
 
 **SpecShield** is the one CLI that does four things to keep your API safe:
 
@@ -215,7 +242,9 @@ specshield compare base.yaml target.yaml --ignore "DELETE /admin removed" --fail
 
 ## Remote Compare
 
-Sends your specs to SpecShield and stores results in your dashboard. Requires a free account.
+Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
+heavy comparison off your CI runner and for cross-validating against the
+exact engine the dashboard uses. Requires a free account.
 
 ```bash
 specshield compare base.yaml target.yaml --remote
@@ -223,9 +252,29 @@ specshield compare base.yaml target.yaml --remote --fail-on-breaking
 specshield compare base.yaml target.yaml --remote --json --output result.json
 ```
 
+> **History note:** `--remote` runs the diff on our servers but currently
+> does **not** persist the result to your comparison history (saving is
+> UI-only right now — see the
+> [Comparison History](#comparison-history) section below). To save a
+> comparison, run it from the dashboard at
+> [specshield.io/account/compare](https://specshield.io/account/compare).
+> A CLI-driven save is on the roadmap.
+
 ## Comparison History
 
-Every `specshield compare --remote` is saved to your account. List recent comparisons from any machine — useful for tracking API drift over time across CI pipelines + local runs.
+> **Status: currently UI-only.** Comparison history is available in the
+> dashboard at [specshield.io/account/history](https://specshield.io/account/history).
+> The `specshield history` CLI command exists but currently exits with a
+> "use the dashboard" message — a CLI-callable API endpoint is on the
+> roadmap (the backend's `/me/*` routes require browser-session JWT auth,
+> not the CLI's API key). The dashboard shows the same data and adds
+> per-comparison drill-down.
+
+Every comparison you run **in the dashboard's `/account/compare` page** is
+saved to your account. Useful for tracking API drift over time across team
+members + machines.
+
+The CLI command (once the backend endpoint ships):
 
 ```bash
 specshield history                # last 20 comparisons
@@ -233,6 +282,8 @@ specshield history --limit 50
 specshield history --json
 ```
 
+Expected output (once enabled):
+
 ```
   Your recent comparisons
   ─────────────────────────────────────────────────────
@@ -243,7 +294,15 @@ specshield history --json
 
 ## Share a Comparison
 
-Generate a public, tokenized URL for any comparison report. Great for Slack threads, PR comments, Jira tickets.
+> **Status: currently UI-only.** Share links are generated from the
+> dashboard — open any comparison at
+> [specshield.io/account/history](https://specshield.io/account/history)
+> and click the "Share" button. Same `/r/<token>` URL shape. The
+> `specshield share` CLI command currently exits with a "use the dashboard"
+> message; CLI integration ships when the backend exposes a CLI-callable
+> share-link endpoint.
+
+Once enabled, the CLI usage will be:
 
 ```bash
 # Share an existing report by ID (from `specshield history`)
@@ -262,7 +321,8 @@ specshield share 482 --expires 30
     Expires:  2026-06-16T12:34:56Z
 ```
 
-Links use a 256-bit random token (unguessable by enumeration). Revoke any time from the dashboard.
+Links use a 256-bit random token (unguessable by enumeration). Revoke any
+time from the dashboard.
 
 ## GitHub App — PR Checks
 
@@ -486,63 +546,362 @@ specshield bdct can-i-deploy --org acme-store --service payment-service --versio
 
 ---
 
-# `bdct capture from-har` — record real traffic, get a consumer contract
+# `bdct capture from-har` — turn real traffic into a consumer contract
+
+**This is the feature that makes BDCT actually work for normal teams.**
+Pact requires every consumer team to learn a DSL, instrument their tests,
+and run a broker. SpecShield asks for something they already have: a
+recording of an HTTP test run, in the universal HAR format that every
+browser, every test framework, and every recording proxy already produces.
+
+A hand-written consumer contract drifts the moment you forget a field. A
+HAR-derived contract reflects what your code **actually called**, every
+time you re-record. It's the difference between "we documented the
+integration" and "we proved the integration."
 
-**The Pact alternative for teams that don't want to adopt a DSL.**
+### The 3-step mental model
 
-`from-har` reads a [HAR file](https://en.wikipedia.org/wiki/HAR_(file_format)) (HTTP Archive — any browser, Cypress, Playwright, k6, Insomnia, or Charles Proxy can export one), filters to your provider's host, infers an OpenAPI 3.0 consumer-contract subset from what your tests actually called, and writes it to a file you can publish with `bdct publish-consumer`.
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  1. RECORD                  2. CAPTURE                  3. GATE          │
+│                                                                          │
+│  Your existing test run  →  specshield bdct          →  publish-consumer │
+│  → traffic.har               capture from-har           verify           │
+│  (browser / Playwright /     → consumer-contract.yaml   can-i-deploy     │
+│   Cypress / mitmproxy /                                                  │
+│   Postman / k6 / …)         ← language-agnostic       ← every provider   │
+│                              CLI does the OpenAPI       PR re-checks     │
+│                              inference                  every consumer   │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+Step 1 already happens in your team — you're just saving the file. Step 2
+is one CLI command. Step 3 is the BDCT registry you publish to.
+
+---
+
+## Step 1 — record a HAR file
 
-Why this matters: a hand-written consumer subset can be wrong (you forget the `currency` field your code reads, and the provider can remove it without anyone noticing). A HAR recording **captures what your code actually does** — without the Pact DSL, language-agnostic, runs anywhere.
+Pick the recorder that matches **how the consumer is exercised** in your
+project. You almost never have to write recorder code yourself.
 
-### Generate a contract from a recorded test run
+| Recorder | Use when the consumer is… | Effort |
+|---|---|---|
+| **[Browser DevTools](https://developer.chrome.com/docs/devtools/network/reference#save)** (Chrome / Firefox / Edge / Safari) | A frontend SPA, a Swagger UI, or any browser-driven app | Zero code |
+| **[Playwright](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har)** with `recordHar` | Exercised by Playwright UI/integration tests | **One config field** |
+| **[Cypress](https://github.com/NeuraLegion/cypress-har-generator)** + `cypress-har-generator` | Exercised by Cypress UI tests | One plugin |
+| **[mitmproxy](https://docs.mitmproxy.org/stable/addons-examples/#har-dump)** | A backend service-to-service caller in a test env | One brew install, no consumer changes |
+| **[Postman](https://learning.postman.com/docs/getting-started/importing-and-exporting/exporting-postman-data/#exporting-as-har)** / Insomnia / Bruno | Manually exercised during exploratory testing | Right-click → export |
+| **[k6](https://grafana.com/docs/k6/latest/results-output/real-time/json/#har)** load tests | Already running k6 against the provider | One `--out har=…` flag |
+
+**Recipes follow** — keep reading for the exact commands per tool, then jump
+to Step 2 (the capture command, which is identical regardless of recorder).
+
+### 1a. Chrome / Firefox / Edge DevTools (zero code — best for frontend)
+
+1. Open the page that calls your API in the browser.
+2. Open DevTools (`F12` / `Cmd+Opt+I`) → **Network** tab.
+3. Click the 🚫 button to clear, then reload the page and click through the
+   flows you want to record.
+4. Right-click anywhere in the request list → **Save all as HAR with
+   content** → save as `traffic.har`.
+
+That's the entire recording. The file is byte-compatible with everything
+SpecShield does.
+
+> **Safari note:** Safari's "Export HAR" is under the Develop menu →
+> *Export…* in the Network tab; it produces the same format.
+
+### 1b. Playwright (best for teams with UI tests)
+
+Add one option to your `playwright.config.js`:
+
+```js
+// playwright.config.js
+const path = require('path');
+module.exports = {
+  testDir: './tests',
+  use: {
+    baseURL: 'https://staging.acme.com',
+    recordHar: { path: path.resolve(__dirname, 'traffic.har'), mode: 'full', content: 'embed' },
+  },
+};
+```
+
+Run your tests as usual:
 
 ```bash
-# Record a HAR (one of many ways)
-#   - Chrome DevTools → Network → right-click → "Save all as HAR"
-#   - Playwright:  page.on('request')... or use BROWSER_TOOLS_HAR
-#   - Cypress:     cy.intercept(...) + plugins like cypress-har-generator
-#   - k6:          k6 run --out har=run.har script.js
+npx playwright test
+# → writes traffic.har on context close
+```
+
+The HAR will contain every HTTP call the browser made during the test —
+HTML, JS, images, and the API JSON. The `--onlyJson` default in Step 2
+filters out the noise automatically.
+
+> Need the HAR file flushed **per test**? Create the context explicitly in
+> your test and call `await context.close()` at the end. A runnable
+> copy-paste starter lives in [`examples/playwright-har/`](examples/playwright-har/)
+> of this repo — clone, `npm install`, `npx playwright install chromium`,
+> `npm test` produces `traffic.har` against the public JSONPlaceholder
+> sandbox so you can verify the toolchain works before pointing it at your
+> own provider.
 
+### 1c. Cypress
+
+```bash
+npm i -D @neuralegion/cypress-har-generator
+```
+
+```js
+// cypress.config.js
+const { install } = require('@neuralegion/cypress-har-generator');
+module.exports = { e2e: { setupNodeEvents(on, config) { install(on); return config; } } };
+
+// cypress/support/e2e.js
+beforeEach(() => cy.recordHar());
+afterEach(() => cy.saveHar({ outDir: './har-out' }));
+```
+
+Run `npx cypress run` and the HAR for each spec lands in `har-out/`.
+
+### 1d. mitmproxy (best for backend service-to-service)
+
+When the consumer is a backend service (no browser), point it through
+mitmproxy in your integration-test env. No consumer code change.
+
+```bash
+# Install once
+brew install mitmproxy            # macOS — also available via pip and apt
+
+# Start the proxy and tell it to dump HAR
+mitmdump --set hardump=traffic.har --listen-port 8080
+
+# In another terminal: run your tests with HTTPS_PROXY pointing at it
+HTTPS_PROXY=http://localhost:8080 HTTP_PROXY=http://localhost:8080 \
+  ./run-integration-tests.sh
+
+# Ctrl-C mitmdump when done — traffic.har is on disk
+```
+
+The `hardump` add-on is built into mitmproxy ≥ 9.0. For TLS hosts you'll
+need to trust mitmproxy's CA in your test JVM/runtime (see the
+[mitmproxy CA docs](https://docs.mitmproxy.org/stable/concepts-certificates/));
+in many test environments it's a single env var
+(`NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, or a
+JVM `cacerts` import).
+
+### 1e. Postman / Insomnia / Bruno
+
+Run the request (or a whole collection runner). Right-click the response
+→ **Save Response as HAR**. Repeat for each request you want included,
+then either keep them as separate `.har` files (pass `--in` once per file
+via a loop in CI) or merge them with any HAR-merge tool.
+
+### 1f. k6 load test (bonus — recording while load-testing)
+
+```bash
+k6 run --out har=traffic.har script.js
+```
+
+k6 emits a HAR alongside its load metrics. Same file works with
+`bdct capture from-har`.
+
+---
+
+## Step 2 — turn the HAR into a consumer contract
+
+This is the one CLI command. The same command works regardless of which
+recorder produced the HAR.
+
+```bash
 specshield bdct capture from-har \
-  --in tests/checkout-run.har \
+  --in       traffic.har \
   --base-url https://api.acme.com \
-  --out contracts/checkout-ui-payment.yaml
+  --out      consumer-contract.yaml
 ```
 
+Expected output:
+
 ```
-✔ Wrote contracts/checkout-ui-payment.yaml  (2 endpoints, 3 ops from 17/24 entries)
+✔ Wrote consumer-contract.yaml  (4 endpoints, 6 ops from 23/41 entries)
 ```
 
-### Options
+The `23/41` summary means **23 entries** survived the filters (right host,
+JSON body) out of **41 total** the recorder captured. Open the YAML to see
+exactly what your code talks to — endpoint by endpoint, field by field.
 
-| Flag | Purpose |
-|---|---|
-| `--in <path>`           | **Required.** Input HAR file (HTTP Archive 1.2). |
-| `--out <path>`          | Output file (default: stdout). |
-| `--base-url <url>`      | Keep only entries matching this URL prefix (e.g. `https://api.acme.com` or `https://api.acme.com/v1`). |
-| `--method <verbs>`      | Comma-separated methods to include (e.g. `GET,POST`). Default: all. |
-| `--title <title>`       | OpenAPI `info.title`. Default: `Captured consumer contract`. |
-| `--version <ver>`       | OpenAPI `info.version`. Default: `0.1.0`. |
-| `--format <fmt>`        | Output format: `yaml` (default) or `json`. |
-| `--include-non-json`    | Keep entries with non-JSON bodies (default: drop them — schemas can't be inferred). |
+### All options
 
-### What you get
+| Flag | Purpose | Default |
+|---|---|---|
+| `--in <path>`           | **Required.** Input HAR file (HAR 1.2). | — |
+| `--out <path>`          | Output file. If omitted, writes to stdout. | stdout |
+| `--base-url <url>`      | Keep only entries matching this URL prefix. Critical when the consumer talks to multiple backends — see "multi-host" below. | (no filter — keeps every host) |
+| `--method <verbs>`      | Comma-separated methods to include, e.g. `GET,POST`. | all methods |
+| `--title <title>`       | OpenAPI `info.title`. | `Captured consumer contract` |
+| `--version <ver>`       | OpenAPI `info.version` — usually your git SHA in CI. | `0.1.0` |
+| `--format <fmt>`        | `yaml` or `json`. | `yaml` |
+| `--include-non-json`    | Keep entries with non-JSON bodies (HTML, images, binary). Schemas can't be inferred but the endpoints will appear. | off |
+
+### What the engine actually does
+
+For every HAR entry that passes the filters:
+
+- **Path templating.** `/users/123/orders/abc-2026` becomes
+  `/users/{userId}/orders/{orderId}`. Parameter names come from the
+  preceding noun in the URL — *not* a generic `{id}` — so the resulting
+  OpenAPI matches the parameter names your provider likely already uses
+  (`{userId}`, `{orderId}`, `{accountId}`, …).
+- **Per-status schema merging.** If three `GET /users/{userId}` samples
+  return slightly different shapes, the emitted schema is the *merger*:
+  fields seen in **every** sample stay `required`; fields seen in **some**
+  samples become optional; `integer` + `number` widens to `number`; a
+  type conflict falls back to `string`.
+- **Format detection.** UUIDs, RFC 3339 date-times, and email addresses
+  get `format: uuid` / `format: date-time` / `format: email`.
+- **Status-code coverage.** A 404 sample produces its own response schema
+  alongside the 200 — so the contract documents the error shapes your code
+  handles, not just the happy path.
+- **JSON-only by default.** Entries with non-JSON bodies are dropped; the
+  HTML page load from a Playwright test never ends up in the contract.
 
-- **Path templating:** concrete paths like `/users/123/orders/abc-2026` are turned into `/users/{userId}/orders/{orderId}` (the param is named from the preceding noun, not a generic `{id}`).
-- **Per-status schema merging:** if two recorded GETs return slightly different shapes, the emitted schema is the merger — fields seen in EVERY sample stay `required`, fields seen in only SOME become optional, integer + number widens to number.
-- **Format detection:** UUIDs, RFC 3339 date-times, and emails get `format: uuid|date-time|email`.
-- **JSON-only by default:** non-JSON bodies are dropped (schemas can't be inferred from binary/HTML); override with `--include-non-json` for debugging.
+---
 
-### Use the captured contract in BDCT
+## Step 3 — publish + gate
 
 ```bash
+# 1. Publish the captured contract (run on every consumer PR)
 specshield bdct publish-consumer \
-  --org acme-store --consumer checkout-ui \
-  --provider payment-service --version 2.0.0 \
-  --contract contracts/checkout-ui-payment.yaml \
-  --format OPENAPI
+  --org   acme-store \
+  --consumer checkout-ui \
+  --provider payment-service \
+  --version  "$GIT_SHA" \
+  --format   OPENAPI \
+  --contract consumer-contract.yaml
+
+# 2. Gate the deploy (run before promoting the consumer)
+specshield bdct can-i-deploy \
+  --org acme-store \
+  --service checkout-ui --version "$GIT_SHA" --env staging
+# exit 0 = safe; exit 1 = a verification says NO and the deploy is blocked
+```
+
+Full BDCT command reference is in the [Bi-Directional Contract Testing](#bi-directional-contract-testing-bdct)
+section above.
+
+---
+
+## Operational concerns (read this before going live)
+
+### Scrubbing auth tokens, cookies, and PII
+
+A raw HAR can contain `Authorization` headers, session cookies, and real
+PII in request/response bodies. **Scrub before publishing.** Two patterns:
+
+**Quick scrub with jq** (zero deps if you already have jq):
+
+```bash
+jq 'del(.. | .headers? | .[]? | select(.name | ascii_downcase | IN("authorization","cookie","set-cookie","x-api-key")))' \
+  traffic.har > scrubbed.har
+```
+
+**Heavier scrub via `har-sanitizer`** (npm tool — supports body redaction
+patterns, allowlists, etc.):
+
+```bash
+npx har-sanitizer --input traffic.har --output scrubbed.har --scrub-words 'email,ssn,creditCard'
+```
+
+The contract that `bdct capture from-har` emits only carries field *names
+and types* — not values — so once the HAR is scrubbed of secrets, the
+published contract is safe to share with the provider team.
+
+### Multi-host filtering (consumer talks to several backends)
+
+`--base-url` is a prefix match, so it doubles as a host filter:
+
+```bash
+# Keep only calls to the payment service
+specshield bdct capture from-har \
+  --in traffic.har --base-url https://payment.acme.com \
+  --out contracts/checkout-ui-payment.yaml
+
+# Same HAR, different provider — keep only calls to inventory
+specshield bdct capture from-har \
+  --in traffic.har --base-url https://inventory.acme.com \
+  --out contracts/checkout-ui-inventory.yaml
 ```
 
+One test run → one HAR → N consumer contracts, one per provider.
+
+### Keeping contracts fresh in CI
+
+The whole pattern is "record from your existing tests, publish from CI." A
+typical `.github/workflows/contract-test.yml`:
+
+```yaml
+- name: Run integration tests (produces traffic.har)
+  run: npx playwright test            # or ./mvnw verify, or whatever you use
+
+- name: HAR → consumer contract
+  run: |
+    specshield bdct capture from-har \
+      --in traffic.har \
+      --base-url ${{ vars.PROVIDER_BASE_URL }} \
+      --out consumer-contract.yaml
+
+- name: Publish contract
+  env:
+    SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
+  run: |
+    specshield bdct publish-consumer \
+      --org ${{ vars.SPECSHIELD_ORG }} \
+      --consumer ${{ vars.SERVICE_NAME }} \
+      --provider ${{ vars.PROVIDER_NAME }} \
+      --version  ${{ github.sha }} \
+      --format   OPENAPI \
+      --contract consumer-contract.yaml
+
+- name: Gate the deploy
+  env:
+    SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
+  run: |
+    specshield bdct can-i-deploy \
+      --org ${{ vars.SPECSHIELD_ORG }} \
+      --service ${{ vars.SERVICE_NAME }} \
+      --version ${{ github.sha }} \
+      --env staging
+```
+
+Identical pattern on GitLab, CircleCI, Jenkins — only the secret-injection
+syntax changes.
+
+### Common pitfalls
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `0 endpoints, 0 ops from 0/N entries` | `--base-url` doesn't match any host in the HAR | Drop `--base-url` to see what hosts ARE in the HAR; re-run with the right prefix. |
+| Contract is missing your POST | Recorder captured a 4xx for that POST | Fix the test so the POST succeeds, OR keep the 4xx (it'll document the error path). |
+| Path got templated when you didn't want it to | A literal path segment looked like a numeric/UUID id | Path segments are templated when **multiple** entries share a prefix but differ on that segment. A single entry stays literal. |
+| Playwright HAR file is empty / not written | `context.close()` didn't run | Create the context explicitly with `chromium.launch()` → `browser.newContext({ recordHar })` and `await context.close()` at the end of the test. |
+| Backend rejects POST when mitmproxy is in the path | TLS cert not trusted by the consumer | See the mitmproxy CA-cert link above; one env var or one JKS import. |
+
+---
+
+## Why this is the most valuable piece of the CLI
+
+Every other contract-testing product on the market asks the consumer team
+to **change their code** — adopt a DSL, instrument their tests, run a
+broker. That tax is why most teams that "should" be doing contract testing
+aren't.
+
+`bdct capture from-har` removes the tax. Your team's existing test run is
+already the contract; the CLI just converts the format. The HAR-capture →
+publish → can-i-deploy loop is what turns "we have OpenAPI specs in a
+folder" into "no provider PR merges if it would break a deployed consumer"
+— with measurable enforcement, in one CI step, and no per-language SDK.
+
 ---
 
 # `bdct verify-provider` — does your live provider actually match its spec?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "3.2.4",
+  "version": "3.2.6",
   "description": "CLI for OpenAPI breaking change detection and bi-directional contract verification — with can-i-deploy gating, GitHub PR checks, and a first-run setup wizard.",
   "main": "src/cli.js",
   "bin": {

package/src/commands/compare.js

@@ -96,6 +96,21 @@ compare
           await fsExtra.outputFile(options.output, JSON.stringify(jsonOutput, null, 2));
           logger.info(`Results saved to ${options.output}`);
         }
+
+        // Honest note for --remote when the backend didn't return a history
+        // ID. The `/compare` endpoint runs the diff but does NOT persist to
+        // the user's comparison history when called with X-Api-Key auth —
+        // that's a UI-only path right now (see the share/history commands).
+        // When/if the backend starts returning historyId, this note auto-hides.
+        if ((options.remote || options.remoteUrl)
+            && !result.historyId && !result.reportId && !result.id) {
+          const chalk = require('chalk');
+          process.stdout.write('\n' + chalk.gray(
+            '  Note: --remote ran the diff on our servers but did NOT save it to your\n' +
+            '  comparison history (history save is currently UI-only). For history, run\n' +
+            '  the compare in the dashboard at https://specshield.io/account/compare.\n'
+          ));
+        }
       }
 
       // Contextual signup nudge — runs only when the user isn't logged in,

package/src/commands/history.js

@@ -49,6 +49,17 @@ history
       });
       if (spinner) spinner.stop();
 
+      // The /me/* routes currently require JWT (browser session) auth — the
+      // CLI's X-Api-Key isn't accepted, so the backend redirects to /login
+      // and axios follows the 302 to the SPA's HTML shell. Detect that and
+      // tell the user where the feature really lives, instead of silently
+      // returning an empty list.
+      if (typeof response.data === 'string'
+          && (response.data.includes('<!doctype') || response.data.includes('<html'))) {
+        printWebOnlyMessage(opts);
+        process.exit(2);
+      }
+
       const items = response.data?.content
                  || response.data?.items
                  || (Array.isArray(response.data) ? response.data : []);
@@ -107,4 +118,31 @@ function printSignupNudge() {
   console.log('');
 }
 
+/**
+ * Surfaced when the backend redirects our API-key request to /login (HTML
+ * response). The /me/compare-history endpoint is currently JWT-only — the
+ * web UI signs in via OAuth and uses a browser-session JWT. A CLI-callable
+ * API endpoint is on the roadmap; until then, the dashboard is the way.
+ */
+function printWebOnlyMessage(opts) {
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({
+      error: 'CLI_UNAVAILABLE',
+      message: 'Comparison history is currently UI-only. The CLI API endpoint is on the roadmap.',
+      dashboard: 'https://specshield.io/account/history',
+    }, null, 2) + '\n');
+    return;
+  }
+  console.log('');
+  console.log(chalk.bold('  Comparison history is currently UI-only.'));
+  console.log('');
+  console.log('  View your comparisons at:');
+  console.log('    ' + chalk.cyan('https://specshield.io/account/history'));
+  console.log('');
+  console.log(chalk.gray('  CLI access is on the roadmap — needs a backend API endpoint that'));
+  console.log(chalk.gray('  accepts the CLI\'s X-Api-Key auth (currently `/me/*` routes require'));
+  console.log(chalk.gray('  the browser-session JWT). Until then, use the dashboard.'));
+  console.log('');
+}
+
 module.exports = history;

package/src/commands/share.js

@@ -50,6 +50,14 @@ share
       process.exit(2);
     }
 
+    // The share-link endpoint lives on `/me/*` which currently requires
+    // browser-session JWT auth — the CLI's X-Api-Key gets redirected to
+    // /login. Until the backend exposes a CLI-callable endpoint, point
+    // users at the dashboard rather than letting the request fail opaquely.
+    printWebOnlyMessage();
+    process.exit(2);
+
+    // eslint-disable-next-line no-unreachable
     const spinner = ora('Generating share link...').start();
     try {
       const headers = { 'X-Api-Key': apiKey, 'X-SpecShield-Client': 'cli' };
@@ -118,4 +126,23 @@ function printSignupNudge() {
   console.log('');
 }
 
+/**
+ * Surfaced because `/me/share-links` currently requires JWT (web sign-in).
+ * The CLI X-Api-Key gets redirected to /login. Until a CLI-callable endpoint
+ * exists, the dashboard is the way.
+ */
+function printWebOnlyMessage() {
+  console.log('');
+  console.log(chalk.bold('  Share links are currently UI-only.'));
+  console.log('');
+  console.log('  Generate a share link at:');
+  console.log('    ' + chalk.cyan('https://specshield.io/account/history'));
+  console.log('  (open any comparison → click "Share").');
+  console.log('');
+  console.log(chalk.gray('  CLI access is on the roadmap — needs a backend API endpoint that'));
+  console.log(chalk.gray('  accepts the CLI\'s X-Api-Key auth (currently `/me/*` routes require'));
+  console.log(chalk.gray('  the browser-session JWT). Until then, use the dashboard.'));
+  console.log('');
+}
+
 module.exports = share;