specshield 3.1.1 → 3.2.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# SpecShield CLI changelog
+
+## 3.2.0 — 2026-05-17 — Conversion fixes
+
+Three CLI changes designed to make the Cloud features (history, share URLs,
+PR checks, BDCT) visible to the 2,000+ existing CLI users who run local
+`specshield compare` but never discover what signing up unlocks.
+
+### Added
+
+- **Post-install welcome banner** — runs once after a fresh `npm install -g specshield`.
+  Briefly explains the value progression (Local → Cloud Free → Pro) and points
+  to the next command to try. Skipped automatically in CI, in non-TTY shells,
+  on update installs, and when `SPECSHIELD_NO_BANNER=1` is set.
+
+- **Contextual signup prompt after `specshield compare`** — after 3+ compares
+  per week, a soft 3-line nudge appears below the regular output:
+  ```
+  ● Track these comparisons over time:
+    specshield login   # 30-sec signup via GitHub / Google · no credit card
+    Unlocks: compare history, shareable report URLs, PR badge
+  ```
+  Throttled to once per week so it never spams. Suppressed entirely for
+  logged-in users, `--json` output, CI environments, and on opt-out. The
+  prompt copy escalates at 10 and 25 compares per window.
+
+- **`specshield history`** — new command to list recent comparisons saved
+  in your Cloud account. Surfaces in `specshield --help` so local-only
+  users discover the feature exists.
+
+- **`specshield share <report-id | base.yaml target.yaml>`** — generate a
+  public shareable URL for a comparison. Designed for pasting diffs into
+  Slack, PR comments, or Jira. Cloud account required.
+
+Both new commands print a friendly "Get started in 30 seconds" message
+with a `specshield login` deep link when run without credentials.
+
+### Why
+
+Background: in May 2026 the CLI had 2,000+ active monthly users (npm download
+estimate; real human count likely 200-500) but the SpecShield Cloud signup
+rate from the CLI was effectively zero. Local compare was so capable that
+users got 100% of their immediate value without ever needing an account.
+
+These changes don't remove any free functionality — local compare is still
+fully usable without signup — they just make the gap between local and
+cloud visible at the moments when a user is most engaged (post-install,
+post-compare, on `--help`).
+
+### Tests
+
+- Added `tests/core/conversionPrompt.test.js` covering all skip conditions,
+  threshold logic, escalation, and 7-day window reset (10 tests).
+- All 134 existing tests still pass.
+
+### Opting out
+
+If you don't want the banner or contextual prompts:
+
+```sh
+export SPECSHIELD_NO_BANNER=1     # disable banner + post-compare nudge
+```
+
+Or just sign up — logged-in users never see either.

package/README.md

@@ -137,6 +137,15 @@ specshield bdct can-i-deploy --version $GITHUB_SHA
 
 See [§ specshield init](#specshield-init--first-run-setup-wizard) below.
 
+> **Quiet install for CI / Docker images:**
+> The post-install welcome banner auto-detects CI environments (`CI`,
+> `GITHUB_ACTIONS`, `BUILDKITE`, `CIRCLECI`, `GITLAB_CI`, `JENKINS_URL`,
+> `TRAVIS`, `TF_BUILD`) and skips itself there — so your CI logs stay clean.
+> To silence it on a workstation too:
+> ```bash
+> export SPECSHIELD_NO_BANNER=1
+> ```
+
 ---
 
 ## 🚀 Create Your Free Account
@@ -160,7 +169,9 @@ See [§ specshield init](#specshield-init--first-run-setup-wizard) below.
 | Breaking change detection | ✅ | ✅ | ✅ |
 | JSON / human output | ✅ | ✅ | ✅ |
 | Fail CI on breaking change | ✅ | ✅ | ✅ |
-| **Compare history & dashboard** | ❌ | ✅ | ✅ |
+| **`specshield history` — compare timeline** | ❌ | ✅ | ✅ |
+| **`specshield share` — public report URLs** | ❌ | ✅ | ✅ |
+| **Dashboard** | ❌ | ✅ | ✅ |
 | **GitHub App PR checks** | ❌ | ✅ | ✅ |
 | **BDCT bi-directional contracts** | ❌ | ❌ | ✅ |
 | **BDCT can-i-deploy gating** | ❌ | ❌ | ✅ |
@@ -268,7 +279,16 @@ Done. Your token is stored in `~/.specshield/config.json` — no need to pass it
 export SPECSHIELD_API_KEY=ss_your_token_here
 ```
 
-Token resolution order: `--api-key flag` → `SPECSHIELD_API_KEY` env var → stored config → `.specshield.yml`
+This single env var works for every command — `compare`, `login`, and every
+`bdct` subcommand all read it.
+
+Token resolution order:
+- `compare` / `login`: `--api-key` flag → `SPECSHIELD_API_KEY` env var → stored config → `.specshield.yml`
+- `bdct ...` subcommands: `--api-token` flag → `SPECSHIELD_API_KEY` env var → stored config
+
+> **Why two flag names?** `compare` and `login` were built first and used
+> `--api-key`. The newer `bdct` commands use `--api-token` to keep the word
+> "key" reserved for the stored config concept. The env var unifies both.
 
 ---
 
@@ -313,6 +333,63 @@ specshield compare base.yaml target.yaml --remote --json --output result.json
 
 ---
 
+## Comparison History
+
+Every `specshield compare --remote` is saved to your SpecShield account.
+List the recent comparisons your account has run from any machine — useful
+for tracking API drift over time across CI pipelines + local runs.
+
+```bash
+specshield history                # last 20 comparisons
+specshield history --limit 50     # show more
+specshield history --json         # machine-readable for scripts
+```
+
+```
+  Your recent comparisons
+  ─────────────────────────────────────────────────────
+  482        3 breaking         2026-05-17 14:30   payment-v1.yaml → payment-v2.yaml
+  481        0 breaking         2026-05-17 11:02   user-api.yaml → user-api-updated.yaml
+  480        7 breaking         2026-05-16 18:55   billing-v3.yaml → billing-v4.yaml
+```
+
+Account required — run `specshield login` to set up (free, no credit card).
+
+---
+
+## Share a Comparison
+
+Generate a public, tokenized URL for any comparison report. Anyone with
+the link can view the diff — no SpecShield account needed. Great for
+pasting into Slack threads, PR comments, or Jira tickets.
+
+```bash
+# Share an existing report by ID (from `specshield history`)
+specshield share 482
+
+# Compare two specs and share the result in one step
+specshield share base.yaml target.yaml
+
+# Time-limited link — expires in 30 days
+specshield share 482 --expires 30
+```
+
+```
+  ✔ Share link ready
+  ─────────────────────────────────────────────────────
+    https://specshield.io/r/_Ru8OVubxY3r9zHOsylESaULphCqBYH5jTPYldSMU88
+    Expires:  2026-06-16T12:34:56Z
+
+  Anyone with this link can view the diff — no SpecShield account required.
+```
+
+Links use a 256-bit random token, so they can't be guessed by enumeration.
+Revoke any time from your dashboard at [specshield.io](https://specshield.io).
+
+Account required — `specshield login` to set up.
+
+---
+
 ## GitHub Integration
 
 **Automatic API contract checks on every pull request — no workflow YAML required.**
@@ -421,6 +498,7 @@ from any subdirectory of your project.
 ### Non-interactive (scriptable) mode
 
 ```bash
+# Provider-only project
 specshield init --no-interactive \
   --kind     provider \
   --org      acme-pay \
@@ -428,16 +506,36 @@ specshield init --no-interactive \
   --spec     api/openapi.yaml \
   --env      staging \
   --write-workflow
+
+# Consumer-only project
+specshield init --no-interactive \
+  --kind              consumer \
+  --org               acme-pay \
+  --consumer          checkout-ui \
+  --consumer-provider payment-service \
+  --contract          contracts/payment-service.yaml \
+  --format            OPENAPI \
+  --env               staging
 ```
 
-### Other useful flags
+### All `init` flags
 
 | Flag | Purpose |
 | --- | --- |
-| `--print` | Detect everything, print the proposed YAML, write nothing. Good for `--dry-run` review in CI. |
+| `--no-interactive` | Run without prompts; all required fields must come from flags or `package.json`/git autodetection. |
+| `--print` | Detect everything, print the proposed YAML to stdout, write nothing. Good for `--dry-run` review in CI. |
 | `--force` | Skip the overwrite-confirmation if `.specshield.yml` already exists. |
-| `--server <url>` | Use a non-default SpecShield endpoint (self-hosted / staging). |
-| `--write-workflow` | Also write a starter GitHub Actions workflow under `.github/workflows/`. |
+| `--server <url>` | Use a non-default SpecShield endpoint (self-hosted / staging). Default: `https://specshield.io`. |
+| `--kind <kind>` | `provider`, `consumer`, `both`, or `skip`. Required in `--no-interactive`. |
+| `--org <key>` | Organization key. |
+| `--provider <name>` | Provider service name (used when `--kind=provider|both`). |
+| `--spec <path>` | Path to the provider OpenAPI spec. |
+| `--consumer <name>` | Consumer service name (used when `--kind=consumer|both`). |
+| `--consumer-provider <name>` | The provider this consumer talks to (used when `--kind=consumer|both`). |
+| `--contract <path>` | Path to the consumer contract (OpenAPI or Pact JSON). |
+| `--format <fmt>` | Consumer contract format: `OPENAPI` (default) or `PACT`. |
+| `--env <environment>` | Default environment for BDCT operations. |
+| `--write-workflow` | Also write a starter GitHub Actions workflow under `.github/workflows/specshield-bdct.yml`. |
 
 > **What is _not_ written into `.specshield.yml`:** your API key. It is
 > stored in `~/.specshield/config.json` (set by `specshield login`) or
@@ -471,17 +569,25 @@ specshield bdct publish-provider \
   --provider payment-service \
   --version v2.1.0 \
   --spec ./api/openapi.yaml \
-  --env production
+  --env production \
+  --branch main
 ```
 
 ```
-  ✔  Provider spec published
-     Provider  : payment-service
-     Version   : v2.1.0
-     Env       : production
-     Auto-verifications triggered: 3
+  ✔  Provider Spec Published
+  ─────────────────────────────────────────────────────
+  ID          : 1842
+  Provider    : payment-service
+  Version     : v2.1.0
+  Environment : production
+  Published At: 2026-05-13 14:30:12
+  Verifications triggered: 3
 ```
 
+`--branch` is optional — when present it's stamped on the published spec so you
+can correlate a spec version with the git branch it came from in
+`bdct list-providers`.
+
 ### Publish a Consumer Contract
 
 The consumer contract is an OpenAPI spec that describes only the endpoints the consumer uses:
@@ -522,19 +628,30 @@ specshield bdct publish-consumer \
   --consumer checkout-ui \
   --provider payment-service \
   --version 2.0.0 \
-  --contract ./contracts/checkout-ui-payment.yaml
+  --contract ./contracts/checkout-ui-payment.yaml \
+  --format OPENAPI
 ```
 
 ```
-  ✔  Consumer contract published
-     Consumer    : checkout-ui @ 2.0.0
-     Provider    : payment-service
-     Compatibility: COMPATIBLE
+  ✔  Consumer Contract Published
+  ─────────────────────────────────────────────────────
+  ID          : 942
+  Consumer    : checkout-ui
+  Provider    : payment-service
+  Version     : 2.0.0
+  Format      : OPENAPI
+  Published At: 2026-05-13 14:31:05
+  Verifications triggered: 1
+
+  ➜  Run: specshield bdct verify --consumer checkout-ui --provider payment-service
 ```
 
-If the provider spec is already published, compatibility is checked immediately.
+If the provider spec is already published, compatibility is verified
+automatically — the "Verifications triggered" count reflects that.
 
-**Pact JSON contracts are also accepted** — SpecShield auto-converts them:
+**Pact JSON contracts are also supported** — pass `--format PACT` and point
+`--contract` at a Pact file. The backend stores the format and runs the same
+compatibility engine against your provider's OpenAPI spec:
 
 ```bash
 specshield bdct publish-consumer \
@@ -542,9 +659,12 @@ specshield bdct publish-consumer \
   --consumer checkout-ui \
   --provider payment-service \
   --version 2.0.0 \
-  --contract ./pacts/checkout-ui-payment-service.json
+  --contract ./pacts/checkout-ui-payment-service.json \
+  --format PACT
 ```
 
+`--format` defaults to `OPENAPI` if omitted.
+
 ### Verify Compatibility
 
 Manually trigger a verification between a specific consumer/provider pair:
@@ -596,18 +716,36 @@ specshield bdct can-i-deploy \
   --env production
 ```
 
+Deployable output:
+
 ```
-  ✔  DEPLOYABLE
+  ✔  PASS: payment-service v2.1.0 is deployable in production
+  ─────────────────────────────────────────────────────
+
+  Consumer Verifications
 
-  payment-service v2.1.0 is COMPATIBLE with all 3 consumer(s)
+  Consumer     Version  Status      Verified At
+  ───────────  ───────  ──────────  ───────────────
+  checkout-ui  2.0.0    COMPATIBLE  2026-05-13 14:32
+  mobile-app   1.5.0    COMPATIBLE  2026-05-13 14:32
+  partner-sdk  3.2.1    COMPATIBLE  2026-05-13 14:32
 ```
 
+Blocked output:
+
 ```
-  ✖  NOT DEPLOYABLE
+  ✖  FAIL: payment-service v2.1.0 is NOT deployable in production
+  ─────────────────────────────────────────────────────
+
+  Consumer Verifications
+
+  Consumer     Version  Status        Verified At
+  ───────────  ───────  ────────────  ───────────────
+  checkout-ui  2.0.0    INCOMPATIBLE  2026-05-13 14:32
+  mobile-app   1.5.0    INCOMPATIBLE  2026-05-13 14:32
 
-  payment-service v2.1.0 is INCOMPATIBLE with:
-    checkout-ui@2.0.0 (INCOMPATIBLE)
-    mobile-app@1.5.0  (INCOMPATIBLE)
+  ➜  Run: specshield bdct verify --consumer <NAME> --provider payment-service
+  ➜  to identify and resolve incompatibilities
 ```
 
 Exit codes: `0` = deployable · `1` = blocked · `2` = error
@@ -621,12 +759,17 @@ specshield bdct matrix --org acme-store --env production
 ```
 
 ```
-  Compatibility Matrix  (env: production)
+  BDCT Compatibility Matrix
+  Environment: production
+  ─────────────────────────────────────────────────────
 
-                    payment-service  order-service
-  checkout-ui       COMPATIBLE       COMPATIBLE
-  mobile-app        INCOMPATIBLE     COMPATIBLE
-  partner-sdk       COMPATIBLE       UNKNOWN
+  Consumer \ Provider  payment-service  order-service
+  ───────────────────  ───────────────  ─────────────
+  checkout-ui          COMPATIBLE       COMPATIBLE
+  mobile-app           INCOMPATIBLE     COMPATIBLE
+  partner-sdk          COMPATIBLE       UNKNOWN
+
+  ■ COMPATIBLE  ■ INCOMPATIBLE  ■ UNKNOWN
 ```
 
 ### List Provider Specs
@@ -640,11 +783,15 @@ specshield bdct list-providers --org acme-store --provider payment-service
 ```
 
 ```
-  Provider Specs
-
-  payment-service  v2.1.0   production   2025-05-01
-  payment-service  v2.0.0   staging      2025-04-20
-  order-service    v1.3.0   production   2025-04-28
+  Published Provider Specs
+  ─────────────────────────────────────────────────────
+  Showing 3 of 3 specs
+
+  ID    Provider         Version  Environment  Branch  Published At
+  ────  ───────────────  ───────  ───────────  ──────  ───────────────
+  1842  payment-service  v2.1.0   production   main    2026-05-13 14:30
+  1799  payment-service  v2.0.0   staging      main    2026-04-20 09:11
+  1772  order-service    v1.3.0   production   main    2026-04-28 11:02
 ```
 
 ### List Consumer Contracts
@@ -670,11 +817,14 @@ specshield bdct list \
 ```
 
 ```
-  BDCT Verifications
-
-  Consumer     Consumer Ver  Provider          Provider Ver  Env         Status        Verified At
-  checkout-ui  2.0.0         payment-service   v2.1.0        production  COMPATIBLE    2025-05-01 14:30
-  mobile-app   1.5.0         payment-service   v2.1.0        production  INCOMPATIBLE  2025-05-01 14:30
+  BDCT Verification History
+  ─────────────────────────────────────────────────────
+  Showing 2 of 2 verifications
+
+  ID    Consumer     Provider         Cons Ver  Prov Ver  Status        Environment  Verified At
+  ────  ───────────  ───────────────  ────────  ────────  ────────────  ───────────  ───────────────
+  3081  checkout-ui  payment-service  2.0.0     v2.1.0    COMPATIBLE    production   2026-05-13 14:32
+  3082  mobile-app   payment-service  1.5.0     v2.1.0    INCOMPATIBLE  production   2026-05-13 14:32
 ```
 
 ### BDCT JSON Output
@@ -831,28 +981,60 @@ jobs:
 
 ## Config File
 
-Create `.specshield.yml` in your project root:
+Run [`specshield init`](#specshield-init--first-run-setup-wizard) to generate
+`.specshield.yml` automatically, or hand-write it. Either way, every
+`specshield ...` invocation reads the file from the project root (or any
+parent directory) and uses its values as defaults — CLI flags always win.
+
+The full schema supports both local-compare defaults and BDCT defaults:
 
 ```yaml
-failOnBreaking: true
-severity: error
+schemaVersion: 1
 
+# Local-compare defaults (used by `specshield compare`).
+failOnBreaking: true
+severity: error                  # info | warning | error
 ignore:
-  - "DELETE /admin removed"
+  - "DELETE /admin removed"      # match by substring; repeatable
 
+# Hosted compare (set --remote on the CLI to override).
 remote:
   enabled: false
-  url: "https://specshield.io/compare"
+  url: https://specshield.io/compare
   timeout: 10000
-  # apiKey: ""  ← use env var instead
+  # apiKey is intentionally NOT set here. Use SPECSHIELD_API_KEY in CI
+  # or `specshield login` locally. Never commit a key to a file.
 
+# BDCT defaults (used by every `specshield bdct ...` subcommand).
+bdct:
+  org: acme-pay
+  environment: staging
+  # server: https://specshield.io   # only set for self-hosted / staging
+
+  provider:
+    name: payment-service
+    spec: api/openapi.yaml          # paths are relative to this file
+    # branch: main                  # informational tag on each publish
+
+  # consumer:
+  #   name: checkout-ui
+  #   provider: payment-service
+  #   contract: contracts/payment-service.yaml
+  #   format: OPENAPI               # OPENAPI | PACT
+
+# GitHub App + bdct-action defaults.
 github:
   specPath: api/openapi.yaml
   failOnBreaking: true
   commentOnPr: true
 ```
 
-CLI flags always override config file values.
+When this file is present, BDCT commands collapse to just `--version`:
+
+```bash
+specshield bdct publish-provider --version $GITHUB_SHA
+specshield bdct can-i-deploy     --version $GITHUB_SHA
+```
 
 ---
 
@@ -875,6 +1057,25 @@ specshield compare <base> <target> [options]
 | `--config <path>` | Path to `.specshield.yml` |
 | `--timeout <ms>` | Request timeout for remote mode |
 
+```bash
+specshield history [options]
+```
+
+| Option | Description |
+|---|---|
+| `--limit <n>` | Number of comparisons to list (default 20) |
+| `--json` | Machine-readable JSON output |
+| `--api-key <key>` | Override stored API key |
+
+```bash
+specshield share <reportId | base.yaml target.yaml> [options]
+```
+
+| Option | Description |
+|---|---|
+| `--expires <days>` | Make the link expire after N days (default: never) |
+| `--api-key <key>` | Override stored API key |
+
 ```bash
 specshield bdct <subcommand> [options]
 ```
@@ -885,12 +1086,32 @@ specshield bdct <subcommand> [options]
 | `publish-consumer` | Publish a consumer contract (OpenAPI subset or Pact JSON) |
 | `verify` | Manually trigger verification for a consumer/provider pair |
 | `can-i-deploy` | Check if a service version is safe to deploy |
-| `matrix` | View compatibility matrix across all pairs |
+| `matrix` | Compatibility matrix across all consumer/provider pairs |
 | `list-providers` | List published provider specs |
 | `list-consumers` | List published consumer contracts |
 | `list` | List verification history |
 
-All `bdct` subcommands support `--json` for machine-readable output.
+Every `bdct` subcommand accepts these flags in common:
+
+| Flag | Purpose |
+|---|---|
+| `--org <key>` | Organization key (or read from `.specshield.yml`'s `bdct.org`) |
+| `--json` | Machine-readable JSON output |
+| `--server <url>` | Override SpecShield server URL (self-hosted / staging) |
+| `--api-token <token>` | API token (overrides env / stored config) |
+
+Per-subcommand flags:
+
+| Subcommand | Flags |
+|---|---|
+| `publish-provider` | `--spec <path>`, `--provider <name>`, `--version <ver>`, `--env <env>`, `--branch <branch>` |
+| `publish-consumer` | `--contract <path>`, `--consumer <name>`, `--provider <name>`, `--version <ver>`, `--format OPENAPI\|PACT` |
+| `verify` | `--consumer <name>`, `--provider <name>`, `--consumer-version <ver>`, `--provider-version <ver>`, `--env <env>` |
+| `can-i-deploy` | `--service <name>`, `--version <ver>`, `--env <env>` |
+| `matrix` | `--env <env>` |
+| `list-providers` | `--provider <name>` (filter) |
+| `list-consumers` | `--consumer <name>` (filter), `--provider <name>` (filter) |
+| `list` | `--consumer <name>`, `--provider <name>`, `--env <env>`, `--page <n>`, `--size <n>` |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "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": {
@@ -10,7 +10,8 @@
     "start": "node bin/specshield.js",
     "test": "jest --coverage",
     "test:watch": "jest --watch",
-    "lint": "eslint src tests --ext .js"
+    "lint": "eslint src tests --ext .js",
+    "postinstall": "node scripts/welcome.js || true"
   },
   "keywords": [
     "openapi",
@@ -47,7 +48,9 @@
   "files": [
     "bin",
     "src",
+    "scripts",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {

package/scripts/welcome.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Post-install welcome banner.
+ *
+ * Runs once via the `postinstall` hook in package.json after a fresh
+ * `npm install -g specshield`. Prints a brief value-progression banner so
+ * users discover the cloud features that exist beyond local compare —
+ * historically users would install, run compare, get value, and never look
+ * at the README to find out signup unlocks more.
+ *
+ * We bail out silently in environments where a banner would be noise or
+ * could break automation:
+ *   - CI environment variables present (CI, GITHUB_ACTIONS, BUILDKITE,
+ *     CIRCLECI, GITLAB_CI, JENKINS_URL, TRAVIS, TF_BUILD)
+ *   - npm_config_loglevel is `silent` or `error` (user opted out of noise)
+ *   - SPECSHIELD_NO_BANNER=1 (explicit opt-out)
+ *   - Not running under npm (`npm_command` unset)
+ *   - Update install rather than fresh install (npm_command !== "install")
+ *
+ * No state is written; we let the user's terminal scroll and move on.
+ */
+'use strict';
+
+function shouldSkip() {
+  const env = process.env;
+  if (env.SPECSHIELD_NO_BANNER === '1') return true;
+  if (env.CI || env.GITHUB_ACTIONS || env.BUILDKITE || env.CIRCLECI ||
+      env.GITLAB_CI || env.JENKINS_URL || env.TRAVIS || env.TF_BUILD) {
+    return true;
+  }
+  const loglevel = env.npm_config_loglevel;
+  if (loglevel === 'silent' || loglevel === 'error') return true;
+  // Only show on the user-initiated "install" command. Things like
+  // `npm ci`, `npm update`, transitive dep installs all set npm_command
+  // to something other than 'install'.
+  if (env.npm_command !== 'install') return true;
+  return false;
+}
+
+if (shouldSkip()) {
+  process.exit(0);
+}
+
+// ANSI color helpers — kept local to avoid pulling in chalk during a
+// post-install script (chalk requires node_modules to be fully populated,
+// which is racy during installs).
+const isTTY = !!process.stdout.isTTY;
+const c = (code, s) => (isTTY ? `[${code}m${s}` : s);
+const bold = (s) => c('1', s);
+const dim  = (s) => c('2', s);
+const cyan = (s) => c('36', s);
+const grn  = (s) => c('32', s);
+
+const banner = `
+${bold('SpecShield installed')} ${dim('— OpenAPI breaking-change detection + BDCT')}
+
+  ${bold('Get started')}
+    ${cyan('specshield compare')} base.yaml target.yaml --fail-on-breaking
+    ${cyan('specshield init')}                          ${dim('# project setup wizard')}
+
+  ${bold('Your usage tier')}
+    ${grn('●')} ${bold('Local (free, no account)')}    spec compare, breaking-change detection
+    ${dim('○')} Cloud Free                  ${dim('+ compare history, PR badge, share URLs')}
+    ${dim('○')} Pro                         ${dim('+ BDCT, can-i-deploy, GitHub PR checks, team')}
+
+  ${dim('Sign in when you want history & sharing:')} ${cyan('specshield login')}
+  ${dim('Docs:')} ${cyan('https://specshield.io/docs')}
+`;
+
+process.stdout.write(banner + '\n');

package/src/cli.js

@@ -7,6 +7,8 @@ const initCommand = require('./commands/init');
 const loginCommand = require('./commands/login');
 const logoutCommand = require('./commands/logout');
 const bdctCommand = require('./commands/bdct');
+const historyCommand = require('./commands/history');
+const shareCommand = require('./commands/share');
 
 const program = new Command();
 
@@ -24,6 +26,8 @@ program.addCommand(initCommand);
 program.addCommand(loginCommand);
 program.addCommand(logoutCommand);
 program.addCommand(bdctCommand);
+program.addCommand(historyCommand);
+program.addCommand(shareCommand);
 
 program.parseAsync(process.argv).catch((err) => {
   const logger = require('./utils/logger');

package/src/commands/compare.js

@@ -12,6 +12,7 @@ const { classifyChanges, filterBySeverity } = require('../core/classifyChanges')
 const { formatHuman, formatJson } = require('../core/outputFormatter');
 const { loadConfig } = require('../core/configLoader');
 const { resolveExitCode } = require('../core/exitCode');
+const { recordCompareAndMaybeRender } = require('../core/conversionPrompt');
 const logger = require('../utils/logger');
 const fsExtra = require('fs-extra');
 const { getStoredApiKey } = require('../config/localConfig');
@@ -92,6 +93,22 @@ compare
         }
       }
 
+      // Contextual signup nudge — runs only when the user isn't logged in,
+      // output is human-readable, not in CI, and they've crossed a usage
+      // threshold this week. The recordCompareAndMaybeRender function is
+      // best-effort; any failure (disk read/write, etc.) is silently
+      // swallowed so the conversion path never blocks compare.
+      try {
+        const loggedIn = !!(options.resolvedApiKey ||
+                            process.env.SPECSHIELD_API_KEY ||
+                            await getStoredApiKey());
+        const prompt = await recordCompareAndMaybeRender({
+          loggedIn,
+          jsonOutput: !!options.json,
+        });
+        if (prompt) process.stdout.write('\n' + prompt + '\n');
+      } catch { /* never block on the nudge */ }
+
       // Exit code
       const code = resolveExitCode(result, options);
       process.exit(code);

package/src/commands/history.js

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * `specshield history` — list recent comparisons saved in the user's
+ * SpecShield Cloud account.
+ *
+ * This command's primary value isn't itself — it's that it surfaces a
+ * concrete Cloud-only feature in `specshield --help`, giving local-only
+ * users a visible "what am I missing?" signal. When run without a stored
+ * API key, it prints a brief sign-up nudge rather than failing silently.
+ */
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const ora = require('ora');
+const axios = require('axios');
+const logger = require('../utils/logger');
+const { getStoredApiKey } = require('../config/localConfig');
+
+const HOSTED_API_URL = 'https://specshield.io';
+
+const history = new Command('history');
+
+history
+  .description('Show your recent comparisons (Cloud account required)')
+  .option('--limit <n>', 'How many comparisons to show', '20')
+  .option('--json', 'Machine-readable JSON output')
+  .option('--api-key <key>', 'API key (overrides env / stored config)')
+  .option('--api-url <url>', 'Override hosted API base URL', HOSTED_API_URL)
+  .action(async (opts) => {
+    const apiKey = opts.apiKey
+      || process.env.SPECSHIELD_API_KEY
+      || (await getStoredApiKey())
+      || null;
+
+    if (!apiKey) {
+      printSignupNudge();
+      process.exit(2);
+    }
+
+    const spinner = opts.json ? null : ora('Fetching your comparison history...').start();
+    try {
+      const size = parseInt(opts.limit, 10) || 20;
+      const response = await axios.get(`${opts.apiUrl}/me/compare-history`, {
+        // Backend uses Spring Data Page conventions: page (0-indexed) + size.
+        params: { page: 0, size },
+        headers: { 'X-Api-Key': apiKey, 'X-SpecShield-Client': 'cli' },
+        timeout: 10000,
+      });
+      if (spinner) spinner.stop();
+
+      const items = response.data?.content
+                 || response.data?.items
+                 || (Array.isArray(response.data) ? response.data : []);
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(items, null, 2) + '\n');
+        return;
+      }
+
+      if (items.length === 0) {
+        console.log(chalk.gray('\n  No comparisons in your history yet. Run:'));
+        console.log(chalk.cyan('    specshield compare a.yaml b.yaml --remote\n'));
+        return;
+      }
+
+      console.log('\n  ' + chalk.bold('Your recent comparisons'));
+      console.log(chalk.gray('  ─────────────────────────────────────────────────────'));
+      for (const item of items) {
+        const id      = item.id || item.reportId || '—';
+        const created = item.createdAt || item.timestamp || '—';
+        const breaks  = item.breakingCount ?? item.breakingChanges?.length ?? '—';
+        // CompareHistorySummaryDto exposes base + target spec names — combine
+        // for a "a.yaml → b.yaml" summary that matches what the user typed.
+        const summary = item.baseSpecName && item.targetSpecName
+          ? `${item.baseSpecName} → ${item.targetSpecName}`
+          : (item.summary || item.baseSpecName || '');
+        const breakBadge = breaks === 0 || breaks === '—'
+          ? chalk.green(`${breaks} breaking`)
+          : chalk.red(`${breaks} breaking`);
+        console.log(`  ${chalk.cyan(String(id).padEnd(10))} ${breakBadge.padEnd(18)} ${chalk.gray(String(created))}  ${summary}`);
+      }
+      console.log();
+    } catch (err) {
+      if (spinner) spinner.fail('Could not fetch history');
+      const msg = err.response
+        ? `${err.response.status}: ${JSON.stringify(err.response.data)}`
+        : err.message;
+      logger.error(`Failed to fetch history: ${msg}`);
+      process.exit(2);
+    }
+  });
+
+function printSignupNudge() {
+  console.log('');
+  console.log(chalk.bold('  specshield history') + chalk.gray(' — Cloud feature'));
+  console.log('');
+  console.log('  Comparison history is part of your SpecShield Cloud account.');
+  console.log('  Every ' + chalk.cyan('specshield compare --remote') + ' you run is saved with the diff,');
+  console.log('  date, and a shareable report URL.');
+  console.log('');
+  console.log(chalk.bold('  Get started in 30 seconds:'));
+  console.log('    ' + chalk.cyan('specshield login') + chalk.gray('   # API key from https://specshield.io'));
+  console.log('    ' + chalk.gray('or visit https://specshield.io and sign in with GitHub / Google'));
+  console.log('');
+  console.log('  ' + chalk.gray('Cloud is free for personal use.'));
+  console.log('');
+}
+
+module.exports = history;

package/src/commands/share.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * `specshield share` — generate a public shareable URL for a comparison
+ * report, so users can paste a SpecShield-hosted link into Slack, GitHub
+ * PR comments, or Jira tickets.
+ *
+ * Like the history command, the bigger purpose is making a concrete
+ * Cloud-only feature discoverable from `specshield --help`. Anyone reading
+ * the help output sees "share" listed and discovers there's value behind
+ * signing up.
+ *
+ * Usage:
+ *   specshield share <report-id>             # share an existing remote compare
+ *   specshield share <base.yaml> <target>    # compare-and-share in one step
+ */
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const ora = require('ora');
+const axios = require('axios');
+const logger = require('../utils/logger');
+const { getStoredApiKey } = require('../config/localConfig');
+const { loadSpec } = require('../core/loadSpec');
+
+const HOSTED_API_URL = 'https://specshield.io';
+
+const share = new Command('share');
+
+share
+  .description('Generate a public shareable URL for a comparison (Cloud account required)')
+  .argument('[reportOrBase]', 'Existing report ID, or path to base spec when comparing inline')
+  .argument('[target]', 'Path to target spec when comparing inline (optional)')
+  .option('--expires <days>', 'Make the share link expire after N days (default: never)', null)
+  .option('--api-key <key>', 'API key (overrides env / stored config)')
+  .option('--api-url <url>', 'Override hosted API base URL', HOSTED_API_URL)
+  .action(async (reportOrBase, target, opts) => {
+    const apiKey = opts.apiKey
+      || process.env.SPECSHIELD_API_KEY
+      || (await getStoredApiKey())
+      || null;
+
+    if (!apiKey) {
+      printSignupNudge();
+      process.exit(2);
+    }
+
+    if (!reportOrBase) {
+      logger.error('Usage:\n  specshield share <report-id>\n  specshield share base.yaml target.yaml');
+      process.exit(2);
+    }
+
+    const spinner = ora('Generating share link...').start();
+    try {
+      const headers = { 'X-Api-Key': apiKey, 'X-SpecShield-Client': 'cli' };
+      const expiresInDays = parseInt(opts.expires, 10) || null;
+
+      let reportId;
+      if (target) {
+        // Inline-compare path: run a /compare with --remote semantics to
+        // persist the result, then immediately share the resulting history
+        // row. Two API calls but keeps the backend share endpoint single-purpose.
+        spinner.text = 'Running remote comparison...';
+        const baseSpec   = await loadSpec(reportOrBase);
+        const targetSpec = await loadSpec(target);
+        const compareResp = await axios.post(`${opts.apiUrl}/compare`,
+          { baseSpec, targetSpec },
+          { headers, timeout: 30000 });
+        // The /compare endpoint returns the diff; the persisted history ID is
+        // on the response (added by CompareHistoryService).
+        reportId = compareResp.data?.historyId || compareResp.data?.reportId;
+        if (!reportId) {
+          throw new Error('Comparison succeeded but no history ID was returned — cannot create share link.');
+        }
+        spinner.text = 'Generating share link...';
+      } else {
+        reportId = reportOrBase;
+      }
+
+      const response = await axios.post(`${opts.apiUrl}/me/share-links`,
+        { reportId, expiresInDays },
+        { headers, timeout: 15000 });
+      spinner.stop();
+
+      const url = response.data?.url || response.data?.shareUrl;
+      const expiresAt = response.data?.expiresAt || null;
+
+      console.log('');
+      console.log(chalk.green('  ✔ Share link ready'));
+      console.log('  ─────────────────────────────────────────────────────');
+      console.log('    ' + chalk.cyan(url));
+      if (expiresAt) console.log('    ' + chalk.gray('Expires:  ' + expiresAt));
+      console.log('');
+      console.log(chalk.gray('  Anyone with this link can view the diff — no SpecShield account required.'));
+      console.log('');
+    } catch (err) {
+      spinner.fail('Could not generate share link');
+      const msg = err.response
+        ? `${err.response.status}: ${JSON.stringify(err.response.data)}`
+        : err.message;
+      logger.error(`Share failed: ${msg}`);
+      process.exit(2);
+    }
+  });
+
+function printSignupNudge() {
+  console.log('');
+  console.log(chalk.bold('  specshield share') + chalk.gray(' — Cloud feature'));
+  console.log('');
+  console.log('  Shareable report URLs let you paste a diff into Slack, GitHub PR comments,');
+  console.log('  or Jira tickets — anyone can view without a SpecShield account.');
+  console.log('');
+  console.log(chalk.bold('  Get started in 30 seconds:'));
+  console.log('    ' + chalk.cyan('specshield login') + chalk.gray('   # API key from https://specshield.io'));
+  console.log('    ' + chalk.gray('or visit https://specshield.io and sign in with GitHub / Google'));
+  console.log('');
+  console.log('  ' + chalk.gray('Cloud is free for personal use.'));
+  console.log('');
+}
+
+module.exports = share;

package/src/core/conversionPrompt.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * Contextual signup nudge after a successful `specshield compare`.
+ *
+ * Lives in its own module so the heuristic is easy to read, test, and tune
+ * without touching the compare command. The default state file path is
+ * `~/.specshield/state.json` — same directory as the stored API key so the
+ * "is the user logged in?" check is co-located.
+ *
+ * Trigger conditions (ALL must be true):
+ *   - User is NOT logged in
+ *   - Not in CI (env CI/GITHUB_ACTIONS/etc)
+ *   - Output isn't `--json` (machine-readable)
+ *   - User has run >= 3 compares in the last 7 days
+ *   - We haven't shown a prompt in the last 7 days (don't spam)
+ *
+ * The state file is best-effort; if the disk read or write fails for any
+ * reason we silently skip the prompt — we will never block or fail the
+ * compare command for the sake of a marketing nudge.
+ */
+
+const path = require('path');
+const os = require('os');
+const fsExtra = require('fs-extra');
+const chalk = require('chalk');
+
+// Path is overridable for tests. Production never sets the env var, so the
+// real home-directory state file is used. Tests point this at a temp dir
+// because os.homedir() on POSIX ignores HOME and reads from /etc/passwd.
+const STATE_PATH = process.env.SPECSHIELD_STATE_PATH
+  || path.join(os.homedir(), '.specshield', 'state.json');
+const ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+const COMPARE_THRESHOLD = 3;
+
+/**
+ * Hand-tuned variant strings keyed by the user's compare count tier. We
+ * escalate the value-prop as they prove sustained usage — first prompts
+ * are gentle (just history); deeper-use prompts are richer (BDCT, team).
+ */
+const VARIANTS = [
+  {
+    minCount: 3,
+    body: [
+      `${chalk.cyan('●')} ${chalk.bold('Track these comparisons over time:')}`,
+      `  ${chalk.cyan('specshield login')}   ${chalk.gray('# 30-sec signup via GitHub / Google · no credit card')}`,
+      `  ${chalk.gray('Unlocks: compare history, shareable report URLs, PR badge')}`,
+    ],
+  },
+  {
+    minCount: 10,
+    body: [
+      `${chalk.cyan('●')} ${chalk.bold('You ran 10+ compares this week.')} ${chalk.gray('Your team can collaborate on this:')}`,
+      `  ${chalk.cyan('specshield login')}   ${chalk.gray('# free Cloud account · GitHub PR checks · BDCT · team dashboard')}`,
+    ],
+  },
+  {
+    minCount: 25,
+    body: [
+      `${chalk.cyan('●')} ${chalk.bold('Heavy usage detected.')} ${chalk.gray("Time to gate deploys with can-i-deploy:")}`,
+      `  ${chalk.cyan('specshield login')}   ${chalk.gray('# unlocks BDCT bi-directional contracts · can-i-deploy · audit log')}`,
+      `  ${chalk.gray('Pricing: free for personal use · $29/mo Solo · $89/mo Team (10 seats)')}`,
+    ],
+  },
+];
+
+function isCi() {
+  const e = process.env;
+  return !!(e.CI || e.GITHUB_ACTIONS || e.BUILDKITE || e.CIRCLECI ||
+            e.GITLAB_CI || e.JENKINS_URL || e.TRAVIS || e.TF_BUILD);
+}
+
+async function readState() {
+  try {
+    return await fsExtra.readJson(STATE_PATH);
+  } catch {
+    return {};
+  }
+}
+
+async function writeState(state) {
+  try {
+    await fsExtra.outputJson(STATE_PATH, state, { spaces: 2 });
+  } catch {
+    // Best-effort — never throw from the conversion path.
+  }
+}
+
+/**
+ * Record a successful compare and return the variant string to print
+ * after the regular output (or null to skip the prompt entirely).
+ *
+ * @param {object} opts
+ * @param {boolean} opts.loggedIn    Whether the user has a stored API key
+ * @param {boolean} opts.jsonOutput  True if --json was passed (suppress prompts)
+ * @returns {Promise<string|null>}
+ */
+async function recordCompareAndMaybeRender({ loggedIn, jsonOutput }) {
+  if (loggedIn)   return null;
+  if (jsonOutput) return null;
+  if (isCi())     return null;
+  // Honor the same opt-out as the post-install banner.
+  if (process.env.SPECSHIELD_NO_BANNER === '1') return null;
+
+  const now = Date.now();
+  const state = await readState();
+
+  // Window the compare count: reset the counter once a week so a heavy
+  // burst followed by a long pause doesn't trigger a prompt months later.
+  if (!state.windowStartedAt || (now - state.windowStartedAt) > ONE_WEEK_MS) {
+    state.windowStartedAt = now;
+    state.compareCount = 0;
+  }
+  state.compareCount = (state.compareCount || 0) + 1;
+
+  let prompt = null;
+  if (state.compareCount >= COMPARE_THRESHOLD) {
+    const sinceLast = state.lastPromptAt ? (now - state.lastPromptAt) : Infinity;
+    if (sinceLast >= ONE_WEEK_MS) {
+      prompt = pickVariant(state.compareCount);
+      state.lastPromptAt = now;
+      state.promptsShown = (state.promptsShown || 0) + 1;
+    }
+  }
+
+  await writeState(state);
+  return prompt;
+}
+
+function pickVariant(count) {
+  // Linear scan from most-aggressive to least-aggressive — pick the
+  // highest-min-count variant the user qualifies for.
+  const eligible = VARIANTS.filter(v => count >= v.minCount).sort((a, b) => b.minCount - a.minCount);
+  if (eligible.length === 0) return null;
+  return eligible[0].body.join('\n');
+}
+
+module.exports = { recordCompareAndMaybeRender, STATE_PATH };