specshield 1.0.8 → 1.0.9

package/README.md

@@ -3,17 +3,58 @@
 [![npm](https://img.shields.io/npm/v/specshield)](https://www.npmjs.com/package/specshield)
 [![downloads](https://img.shields.io/npm/dw/specshield)](https://www.npmjs.com/package/specshield)
 [![license](https://img.shields.io/badge/license-MIT-blue)](#license)
-[![node](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org)
+[![node](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org)
 
-## 🚀 Prevent Breaking API Changes Before They Reach Production
+---
+
+> **OpenAPI Diff · Swagger Diff · API Breaking Change Detection · Contract Testing · Pact Alternative · API Governance · CI/CD API Validation · API Drift Detection**
+
+---
+
+## Stop Breaking APIs in Production
+
+**SpecShield** detects breaking API changes and runs contract tests directly in your CI/CD pipeline —
+before they become production incidents.
+
+```
+OpenAPI diff  +  contract testing  +  deployment gating  —  in one CLI.
+```
+
+No broker. No complex setup. Works in 30 seconds.
+
+---
 
-**SpecShield is a Pact alternative for OpenAPI** that helps developers  
-**detect breaking API changes in CI/CD** and act as a powerful  
-**OpenAPI diff tool for modern backend teams.**
+## The Problem
+
+**APIs break silently. Your users feel it first.**
+
+- A backend developer renames a field — the mobile app crashes for 10,000 users
+- An endpoint gets removed — the frontend breaks with no error in your logs
+- A required field changes — partner integrations start failing at 2am
+- You only find out after a production incident, a 3am alert, or an angry customer
+
+Manual code review doesn't catch this. Integration tests run too late.
+**You need a contract between your services — and something that enforces it.**
 
 ---
 
-## 👀 See it in action
+## The Solution
+
+Think of SpecShield as **unit tests for your API contracts**.
+
+- The consumer declares what it expects from the provider
+- The provider proves it satisfies those expectations before deploying
+- SpecShield blocks the deployment if anything breaks
+
+```
+Consumer publishes contract  →  Provider verifies it  →  CI either passes or blocks
+```
+
+No runtime surprise. No production incident. No 3am page.
+
+---
+
+## See It in Action
 
 ```bash
 $ specshield compare base.yaml target.yaml --fail-on-breaking
@@ -21,648 +62,371 @@ $ specshield compare base.yaml target.yaml --fail-on-breaking
 ✖ BREAKING CHANGES DETECTED
 
   1. DELETE /users endpoint removed
-  2. POST /payments request field "amount" changed from optional to required
-  3. GET /orders/{id} response field "status" type changed: string -> object
+  2. POST /payments — "amount" changed from optional to required
+  3. GET /orders/{id} — "status" type changed: string → object
 
-Summary
-- Breaking changes : 3
-- Modifications    : 1
-- Additions        : 2
-- Warnings         : 0
+  Breaking changes : 3
+  Modifications    : 1
+  Additions        : 2
 
-CI Result: FAILED
-Exit Code: 1
+CI Result: FAILED  ·  Exit code: 1
 ```
 
-These are the kinds of changes that break clients in production.  
-SpecShield catches them early so your CI can block unsafe deployments.
+**That 3-line output just saved you a production incident.**
 
-### Safe change example
+And when everything is safe:
 
 ```bash
 $ specshield compare base.yaml target.yaml --fail-on-breaking
 
 ✔ NO BREAKING CHANGES FOUND
 
-Summary
-- Breaking changes : 0
-- Modifications    : 1
-- Additions        : 3
-- Warnings         : 1
+  Breaking changes : 0
+  Modifications    : 0
+  Additions        : 3
 
-CI Result: PASSED
-Exit Code: 0
+CI Result: PASSED  ·  Exit code: 0
 ```
 
 ---
 
-## ⚡ 30-second quick start
+## Quick Start
+
+No account. No login. No config file. Just run it.
 
 ```bash
 npm install -g specshield
+```
+
+```bash
 specshield compare base.yaml target.yaml --fail-on-breaking
 ```
 
-👉 No account required for local compare
+That's it. Works with any OpenAPI 3.x YAML or JSON spec.
 
 ---
 
-## 💡 Useful for
+## 🚀 Create Your Free Account
 
-- Preventing accidental API breakage in pull requests
-- Failing CI when breaking changes are introduced
-- Tracking API drift across versions
-- Enforcing contracts between consumer and provider services
+**Unlock history, dashboards, contract testing, and team features.**
 
----
+👉 **[Create free account at specshield.io](https://specshield.io)**
 
-## 🌐 Upgrade to Remote
+- ✅ No credit card required
+- ✅ Takes less than 30 seconds
+- ✅ GitHub and Google sign-in supported
+- ✅ Local compare always free, forever
 
-Local compare is free and unlimited.
+---
 
-Remote mode unlocks:
+## Local vs Cloud
 
-- 📊 API change history
-- 👥 Team collaboration
-- 🚦 Deployment gating (`can-i-deploy`)
-- 🔗 Contract testing across services
+| Feature | Local (Free) | Cloud (specshield.io) |
+|---|---|---|
+| Compare two spec files | ✅ | ✅ |
+| Breaking change detection | ✅ | ✅ |
+| JSON / human output | ✅ | ✅ |
+| Fail CI on breaking change | ✅ | ✅ |
+| **Compare history & dashboard** | ❌ | ✅ |
+| **Contract testing registry** | ❌ | ✅ |
+| **can-i-deploy gating** | ❌ | ✅ |
+| **Team collaboration** | ❌ | ✅ |
+| **API drift trends** | ❌ | ✅ |
 
-👉 https://specshield.io
+Local is great for getting started. Cloud is what your team ships with.
 
 ---
 
-## Table of Contents
-
-- [What is SpecShield CLI?](#what-is-specshield-cli)
-- [Installation](#installation)
-- [Local Compare](#local-compare)
-- [Authentication](#authentication)
-  - [Generate an API Token](#generate-an-api-token)
-- [Remote Compare](#remote-compare)
-- [Contracts — Consumer-Driven Testing](#contracts--consumer-driven-testing)
-  - [Contract File Format](#contract-file-format)
-  - [Publish a Contract](#publish-a-contract)
-  - [List Contracts](#list-contracts)
-  - [Get Latest Contract](#get-latest-contract)
-  - [Verify a Contract](#verify-a-contract)
-  - [Verification History](#verification-history)
-  - [Can I Deploy?](#can-i-deploy)
-  - [Full Publish → Verify → Deploy Workflow](#full-publish--verify--deploy-workflow)
-  - [Contracts in CI/CD](#contracts-in-cicd)
-- [Config File](#config-file)
-- [All Options](#all-options)
-- [Exit Codes](#exit-codes)
-- [CI/CD — GitHub Actions](#cicd--github-actions)
-- [Support](#support)
+## A Real-World Story
+
+> The `payment-service` team merged a change that renamed `status` to `paymentStatus`
+> in the payment creation response. The `checkout-ui` team wasn't notified.
+>
+> Without SpecShield, this would have reached staging, broken checkout for every user,
+> and triggered an incident at 2am.
+>
+> With SpecShield, the provider's CI ran `specshield contracts verify` against the
+> consumer's published contract. The mismatch was caught immediately:
+>
+> ```
+> ● MISSING_FIELD at $.status
+>   expected: "CREATED"  →  actual: null
+> ```
+>
+> `can-i-deploy` returned exit code `1`. The broken build never deployed.
+> **Zero users affected.**
 
 ---
 
-## What is SpecShield CLI?
+## Use Cases
 
-SpecShield CLI is a developer-first **OpenAPI diff tool** and  
-**contract testing solution** that helps prevent breaking API changes.
+**Pull Request Validation**
+Catch breaking changes before they're merged. Run `specshield compare` against your base branch on every PR.
 
-It works as a lightweight **Pact alternative for OpenAPI**, designed for  
-modern microservices and CI/CD pipelines.
+**CI/CD Gating**
+Fail the build automatically when a breaking change is detected. Exit code `1` triggers your pipeline to stop.
 
-It works in two modes:
+**Microservices Contract Safety**
+Consumer teams publish what they expect. Provider teams verify they deliver it. No cross-team surprises.
 
-| Mode | Description |
-|---|---|
-| **Local** | Compares two spec files on your machine. No account needed. |
-| **Remote** | Sends specs to the SpecShield hosted API. Requires an API token. Results are stored in your dashboard. |
+**API Governance**
+Track API drift over time across your entire platform. Know what changed, when, and which team changed it.
 
 ---
 
-## Installation
+## vs. Alternatives
 
-```bash
-npm install -g specshield
-```
-
-Verify the installation:
-
-```bash
-specshield --version
-```
+| Feature | SpecShield | Pact | openapi-diff |
+|---|---|---|---|
+| OpenAPI / Swagger native | ✅ | ❌ (code-level) | ✅ |
+| No broker required | ✅ | ❌ (needs Pact Broker) | ✅ |
+| Contract testing | ✅ | ✅ | ❌ |
+| Breaking change detection | ✅ | ❌ | ✅ |
+| can-i-deploy gating | ✅ | ✅ (via broker) | ❌ |
+| Hosted dashboard | ✅ | ✅ (Pactflow, paid) | ❌ |
+| Team collaboration | ✅ | ✅ (paid) | ❌ |
+| CLI-first workflow | ✅ | ❌ | ✅ |
+| Free hosted tier | ✅ | ❌ | N/A |
 
 ---
 
-## Local Compare
-
-No account or token required for local comparisons.
-
-```bash
-specshield compare base.yaml target.yaml
-```
-
-Fail CI if breaking changes are found:
-
-```bash
-specshield compare base.yaml target.yaml --fail-on-breaking
-```
+## 🎥 Demo
 
-Output as JSON:
+![SpecShield CLI Demo](demo/specshield-demo.gif)
 
-```bash
-specshield compare base.yaml target.yaml --json
-```
+> `specshield compare payment-api-v1.yaml payment-api-v2.yaml --fail-on-breaking`
 
-Save results to a file:
+---
 
-```bash
-specshield compare base.yaml target.yaml --output result.json
-```
+## Pricing
 
-Ignore specific changes:
+| Plan | Price | What's included |
+|---|---|---|
+| **Free** | $0 forever | Local compare, unlimited. Cloud: compare history, API keys, dashboard |
+| **Pro** | Coming soon | Team collaboration, advanced reporting, priority support |
 
-```bash
-specshield compare base.yaml target.yaml --ignore "DELETE /users removed" --fail-on-breaking
-```
+No credit card ever required for the free plan.
+**[Get started free →](https://specshield.io)**
 
 ---
 
-## Authentication
+## Login & Authentication
 
-Remote compare requires a SpecShield account and an API token.
+**Step 1 — Create your account**
 
-### Sign in to SpecShield
+Go to [https://specshield.io](https://specshield.io) · Sign in with GitHub or Google (30 seconds)
 
-1. Go to [https://specshield.io](https://specshield.io)
-2. Sign in with your email/password, GitHub, or Google account
-3. You will land on your account dashboard
+**Step 2 — Generate an API key**
 
-### Generate an API Token
+Dashboard → **API Keys** → **Generate Key** · Copy the `ss_` token
 
-1. From your dashboard, go to **Account → API Keys**
-   (direct link: [https://specshield.io/account/keys](https://specshield.io/account/keys))
-2. Click **Generate API Key**
-3. Copy the token — it starts with `ss_` and is shown only once
-4. Store it securely (password manager, secrets vault, or CI/CD secret)
-
-### Configure the CLI
-
-Run the login command with your token:
+**Step 3 — Authenticate the CLI**
 
 ```bash
 specshield login --api-key ss_your_token_here
 ```
 
-This validates the token against the SpecShield API and saves it to `~/.specshield/config.json`. You will not need to pass the token on every command after this.
-
-**Example output:**
-
-```text
+```
 ✔ Logged in successfully.
-
-  Customer:  Jane Smith
-  Plan:      FREE
-  Config:    /Users/jane/.specshield/config.json
-
-  Run: specshield compare base.yaml target.yaml --remote
+  Customer : Your Name
+  Plan     : FREE
 ```
 
-### Alternative: Environment Variable
+Done. Your token is stored in `~/.specshield/config.json` — no need to pass it on every command.
 
-If you prefer not to use the stored config (e.g. in CI/CD), set the token as an environment variable:
+**Or use an environment variable (recommended for CI):**
 
 ```bash
 export SPECSHIELD_API_KEY=ss_your_token_here
-specshield compare base.yaml target.yaml --remote
 ```
 
-The token resolution order is:
+Token resolution order: `--api-key flag` → `SPECSHIELD_API_KEY` env var → stored config → `.specshield.yml`
 
-1. `--api-key` flag (highest priority)
-2. `SPECSHIELD_API_KEY` environment variable
-3. Stored config (`~/.specshield/config.json`)
-4. `remote.apiKey` in `.specshield.yml`
+---
 
-### Log Out
+## Local Compare
 
-To remove the stored token:
+No account needed.
 
 ```bash
-specshield logout
+# Basic compare
+specshield compare base.yaml target.yaml
+
+# Fail CI on breaking changes
+specshield compare base.yaml target.yaml --fail-on-breaking
+
+# JSON output
+specshield compare base.yaml target.yaml --json
+
+# Save to file
+specshield compare base.yaml target.yaml --output result.json
+
+# Ignore a specific change
+specshield compare base.yaml target.yaml --ignore "DELETE /admin removed" --fail-on-breaking
 ```
 
 ---
 
 ## Remote Compare
 
-Remote compare sends your spec files to the SpecShield hosted API at [https://specshield.io](https://specshield.io). Results are processed server-side and stored in your dashboard for review.
-
-**When to use remote mode:**
-- You want comparison history tracked in the SpecShield dashboard
-- Your team shares a centralized view of API drift over time
-- You are on a plan with advanced reporting features
-
-### Basic remote compare
+Sends your specs to SpecShield and stores results in your dashboard.
+Requires a free account and API key.
 
 ```bash
+# Remote compare
 specshield compare base.yaml target.yaml --remote
-```
-
-### Remote compare with CI fail on breaking changes
 
-```bash
+# Remote + fail on breaking
 specshield compare base.yaml target.yaml --remote --fail-on-breaking
-```
 
-### Remote compare with JSON output
-
-```bash
+# Remote + JSON output saved to file
 specshield compare base.yaml target.yaml --remote --json --output result.json
 ```
 
-### How authentication works in remote mode
-
-The CLI reads your API token (from flag, env var, or stored config) and sends it as an `X-Api-Key` header with each request. If no token is found, the command exits with an error:
-
-```text
-Error: No API key found. Run: specshield login --api-key <KEY>
-```
-
 ---
 
-## Contracts — Consumer-Driven Testing
+## Contract Testing
 
-SpecShield Contracts lets consumer teams publish API expectations (contracts) to a central registry. Provider teams then verify their service satisfies those contracts before deploying.
+Consumer-driven contract testing for microservices — without a broker.
 
-**Why contract testing?**
-- Catch provider-side regressions before they reach consumers
-- Enforce an agreed-upon API shape across services
-- Gate deployments on verified contracts with `can-i-deploy`
+**How it works:**
 
-All contract commands require an API token. See [Authentication](#authentication).
+1. Consumer team publishes a contract (what they expect from the provider)
+2. Provider team verifies their service satisfies it
+3. `can-i-deploy` gates the deployment based on verification results
 
 ### Contract File Format
 
-Create a `.json` file describing the expected API interactions:
-
 ```json
 {
-  "consumer": {
-    "name": "checkout-ui",
-    "version": "1.2.0"
-  },
-  "provider": {
-    "name": "payment-service"
-  },
+  "consumer": { "name": "checkout-ui", "version": "2.0.0" },
+  "provider": { "name": "payment-service" },
+  "orgKey": "acme-store",
   "contractName": "create-payment",
   "contractType": "HTTP",
   "interactions": [
     {
-      "description": "create payment",
+      "description": "checkout-ui creates a payment",
       "request": {
         "method": "POST",
         "path": "/payments",
-        "headers": {
-          "Content-Type": "application/json"
-        },
-        "body": {
-          "orderId": "ORD-123",
-          "amount": 100,
-          "currency": "INR"
-        }
+        "headers": { "Content-Type": "application/json" },
+        "body": { "orderId": "ORD-123", "amount": 1299, "currency": "INR" }
       },
       "expectedResponse": {
         "status": 201,
-        "headers": {
-          "Content-Type": "application/json"
-        },
-        "body": {
-          "paymentId": "PAY-123",
-          "status": "CREATED"
-        }
+        "headers": { "Content-Type": "application/json" },
+        "body": { "paymentId": "PAY-123", "status": "CREATED" }
       }
     }
-  ],
-  "metadata": {
-    "generatedBy": "specshield-cli",
-    "contractFormatVersion": "1.0"
-  }
+  ]
 }
 ```
 
-The `consumer.name`, `provider.name`, and `contractName` fields are used to identify the contract in the registry. CLI flags (`--consumer`, `--provider`, `--contract-name`) override file values if provided.
-
 ### Publish a Contract
 
 ```bash
-specshield contracts publish \\
-  --file ./contracts/create-payment.json \\
-  --org acme
-```
-
-With all flags explicitly set (flags override file values):
-
-```bash
-specshield contracts publish \\
-  --file ./contracts/create-payment.json \\
-  --org acme \\
-  --consumer checkout-ui \\
-  --provider payment-service \\
-  --contract-name create-payment \\
-  --consumer-version 1.2.0 \\
+specshield contracts publish \
+  --file ./contracts/create-payment.json \
+  --org acme-store \
+  --consumer-version 2.0.0 \
   --tag main
 ```
 
-**Example output:**
-
-```text
-  ✔  Contract Published Successfully
-  ─────────────────────────────────────────────────────
-  Contract ID     : 42
-  Contract Name   : create-payment
-  Consumer        : checkout-ui
-  Provider        : payment-service
-  Version         : 3
-  Status          : PUBLISHED
-  Content Hash    : a3f9c1d2e7b8...
-  Published At    : 06/04/2026 14:30:00
-
-  ➜  Run: specshield contracts verify --contract-id 42 --base-url http://localhost:8080
-```
-
-**Options:**
-
-| Flag | Description |
-|---|---|
-| `--file <path>` | Path to contract JSON file (required) |
-| `--org <key>` | Organization key |
-| `--consumer <key>` | Consumer service key (overrides file) |
-| `--provider <key>` | Provider service key (overrides file) |
-| `--consumer-version <ver>` | Consumer version tag |
-| `--contract-name <name>` | Contract name (overrides file) |
-| `--tag <tag>` | Git branch or release tag |
-| `--server <url>` | SpecShield server URL (default: `https://specshield.io`) |
-| `--api-token <token>` | API token |
-
-### List Contracts
-
-```bash
-specshield contracts list
-```
-
-Filter by provider:
-
-```bash
-specshield contracts list --provider payment-service
-```
-
-Filter by consumer, org, status:
-
-```bash
-specshield contracts list \\
-  --consumer checkout-ui \\
-  --provider payment-service \\
-  --status PUBLISHED
-```
-
-Output raw JSON:
-
-```bash
-specshield contracts list --json
-```
-
-**Example output:**
-
-```text
-  SpecShield Contract Registry
-  ─────────────────────────────────────────────────────
-  Showing 2 of 2 contracts
-
-  ID  Contract Name    Consumer      Provider         Ver  Status     Last Verify  Published
-  ──  ───────────────  ────────────  ───────────────  ───  ─────────  ───────────  ─────────────────────
-  42  create-payment   checkout-ui   payment-service  3    PUBLISHED  SUCCESS      06/04/2026 14:30:00
-  41  get-order-status order-ui      order-service    1    PUBLISHED  FAILED       05/04/2026 09:15:00
-```
-
-**Options:**
-
-| Flag | Description |
-|---|---|
-| `--consumer <key>` | Filter by consumer |
-| `--provider <key>` | Filter by provider |
-| `--org <key>` | Filter by organization |
-| `--status <status>` | Filter by status (`PUBLISHED` / `DEPRECATED`) |
-| `--contract-name <name>` | Filter by contract name |
-| `--page <n>` | Page number (0-based, default: `0`) |
-| `--size <n>` | Page size (default: `20`) |
-| `--json` | Output raw JSON |
-
-### Get Latest Contract
-
-```bash
-specshield contracts latest \\
-  --consumer checkout-ui \\
-  --provider payment-service \\
-  --contract-name create-payment
-```
-
-Print the full contract content (interactions, body, etc.):
-
-```bash
-specshield contracts latest \\
-  --consumer checkout-ui \\
-  --provider payment-service \\
-  --json
-```
-
-**Options:**
-
-| Flag | Description |
-|---|---|
-| `--consumer <key>` | Consumer service key |
-| `--provider <key>` | Provider service key |
-| `--org <key>` | Organization key |
-| `--contract-name <name>` | Contract name |
-| `--json` | Print full contract JSON |
-
 ### Verify a Contract
 
-Run the contract against a live provider. SpecShield replays each interaction against the `--base-url` and compares the response to the expected values.
-
 ```bash
-specshield contracts verify \\
-  --contract-id 42 \\
-  --base-url http://localhost:8080
-```
-
-With version and environment tags:
-
-```bash
-specshield contracts verify \\
-  --contract-id 42 \\
-  --base-url https://payment-service.staging.internal \\
-  --provider-version v2.1.0 \\
+specshield contracts verify \
+  --contract-id 42 \
+  --base-url http://localhost:8080 \
+  --provider-version v2.1.0 \
   --env staging
 ```
 
-Output raw JSON (for CI parsing):
-
-```bash
-specshield contracts verify \\
-  --contract-id 42 \\
-  --base-url http://localhost:8080 \\
-  --json
+Pass output:
 ```
-
-**Example output (pass):**
-
-```text
   ✔  Verification PASSED  (1/1 interactions)
-  ─────────────────────────────────────────────────────
-  Verification ID : 101
-  Contract ID     : 42
-  Status          : SUCCESS
-  Started At      : 06/04/2026 14:35:00
-  Completed At    : 06/04/2026 14:35:01
-
-  ➜  Run: specshield contracts can-i-deploy --provider payment-service --version v2.1.0
 ```
 
-**Example output (fail):**
-
-```text
+Fail output:
+```
   ✖  Verification FAILED  (0/1 interactions passed, 1 failed)
-  ─────────────────────────────────────────────────────
-  Verification ID : 102
-  Contract ID     : 42
-  Status          : FAILED
 
   Mismatches
-  ─────────────────────────────────────────────────────
-  ● [create payment] STATUS_CODE_MISMATCH at $.status
-    expected: 201  →  actual: 200
-    Expected status 201 but got 200
-
-  ➜  Run: specshield contracts history --contract-id 42 to inspect previous runs
+  ● [create payment] MISSING_FIELD at $.status
+    expected: "CREATED"  →  actual: null
 ```
 
-**Exit codes:** `0` = PASSED, `1` = FAILED, `2` = error
-
-**Options:**
-
-| Flag | Description |
-|---|---|
-| `--contract-id <id>` | Contract ID to verify (required) |
-| `--base-url <url>` | Provider base URL (required, e.g. `http://localhost:8080`) |
-| `--provider-version <ver>` | Provider version tag |
-| `--env <environment>` | Environment label (`staging`, `qa`, `production`) |
-| `--mode <mode>` | `LIVE` or `REPLAY` (default: `LIVE`) |
-| `--json` | Output raw JSON |
-
-### Verification History
+### Can I Deploy?
 
 ```bash
-specshield contracts history --contract-id 42
+specshield contracts can-i-deploy \
+  --provider payment-service \
+  --version v2.1.0 \
+  --env staging
 ```
 
-**Example output:**
-
-```text
-  Verification History — Contract 42
-  ─────────────────────────────────────────────────────
-
-  ID   Status   Environment  Provider Version  Mode  Completed At
-  ───  ───────  ───────────  ────────────────  ────  ─────────────────────
-  102  FAILED   staging      v2.1.0            LIVE  06/04/2026 14:35:01
-  101  SUCCESS  staging      v2.0.0            LIVE  05/04/2026 10:00:00
-  98   SUCCESS  qa           v1.9.0            LIVE  01/04/2026 08:30:00
 ```
-
-**Options:**
-
-| Flag | Description |
-|---|---|
-| `--contract-id <id>` | Contract ID (required) |
-| `--json` | Output raw JSON |
-
-### Can I Deploy?
-
-Check whether a provider version has passing verifications for all associated contracts:
-
-```bash
-specshield contracts can-i-deploy \\
-  --provider payment-service \\
-  --version v2.1.0
+  ✔  PASS: payment-service v2.1.0 is deployable in staging
 ```
-
-Scoped to a specific environment:
-
-```bash
-specshield contracts can-i-deploy \\
-  --provider payment-service \\
-  --version v2.1.0 \\
-  --env production
+```
+  ✖  FAIL: payment-service v2.1.0 is NOT deployable in staging
 ```
 
-**Example output (allowed):**
+Exit codes: `0` = deployable · `1` = blocked · `2` = error
 
-```text
-  ✔  PASS: payment-service v2.1.0 is deployable in production
-  ─────────────────────────────────────────────────────
+### List and Inspect Contracts
 
-  Contract Decisions
-  ✔ Contract ID 42 — SUCCESS
-    All contracts verified
+```bash
+specshield contracts list --provider payment-service
+specshield contracts latest --consumer checkout-ui --provider payment-service --json
+specshield contracts history --contract-id 42
 ```
 
-**Example output (blocked):**
+### Full Workflow
 
-```text
-  ✖  FAIL: payment-service v2.1.0 is NOT deployable in production
-  ─────────────────────────────────────────────────────
+```bash
+# 1. Consumer publishes contract
+specshield contracts publish --file ./contracts/create-payment.json --org acme-store
 
-  Contract Decisions
-  ✖ Contract ID 43 — FAILED
-    Unverified or failed contracts found
+# 2. Provider verifies it
+specshield contracts verify --contract-id 42 --base-url http://localhost:8080 --provider-version v2.1.0
 
-  ➜  Run: specshield contracts verify --contract-id 43 --base-url <URL>
-  ➜  to verify pending contracts before deploying
+# 3. Gate the deployment
+specshield contracts can-i-deploy --provider payment-service --version v2.1.0
 ```
 
-**Exit codes:** `0` = deployable, `1` = blocked, `2` = error
+---
 
-**Options:**
+## CI/CD — GitHub Actions
 
-| Flag | Description |
-|---|---|
-| `--provider <key>` | Provider service key (required) |
-| `--version <ver>` | Provider version to check (required) |
-| `--env <environment>` | Target environment |
-| `--json` | Output raw JSON |
+### On Pull Request — Catch breaking changes before merge
 
-### Full Publish → Verify → Deploy Workflow
+```yaml
+name: API Contract Check
 
-```bash
-# 1. Consumer team publishes a contract
-specshield contracts publish \\
-  --file ./contracts/create-payment.json \\
-  --org acme
-
-# 2. Provider team starts their service locally
-./gradlew bootRun &
-
-# 3. Provider team verifies the contract
-specshield contracts verify \\
-  --contract-id 42 \\
-  --base-url http://localhost:8080 \\
-  --provider-version v2.1.0 \\
-  --env staging
+on:
+  pull_request:
+    branches: [main]
 
-# 4. Gate the deployment
-specshield contracts can-i-deploy \\
-  --provider payment-service \\
-  --version v2.1.0 \\
-  --env staging
+jobs:
+  check-api-contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install -g specshield
+      - name: Get base spec
+        run: git show origin/main:api/openapi.yaml > /tmp/base.yaml
+      - name: Compare specs
+        run: specshield compare /tmp/base.yaml api/openapi.yaml --fail-on-breaking
 ```
 
-### Contracts in CI/CD
-
-#### GitHub Actions — Publish on consumer change
+### On Push — Publish consumer contract
 
 ```yaml
 name: Publish Contract
@@ -674,7 +438,7 @@ on:
       - 'contracts/**'
 
 jobs:
-  publish-contract:
+  publish:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -686,13 +450,13 @@ jobs:
         env:
           SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
         run: |
-          specshield contracts publish \\
-            --file ./contracts/create-payment.json \\
-            --org acme \\
+          specshield contracts publish \
+            --file ./contracts/create-payment.json \
+            --org acme-store \
             --tag ${{ github.ref_name }}
 ```
 
-#### GitHub Actions — Verify + can-i-deploy on provider change
+### On Push — Verify provider + gate deployment
 
 ```yaml
 name: Contract Verification
@@ -702,37 +466,30 @@ on:
     branches: [main]
 
 jobs:
-  verify-contracts:
+  verify:
     runs-on: ubuntu-latest
-    services:
-      payment-service:
-        image: myorg/payment-service:${{ github.sha }}
-        ports:
-          - 8080:8080
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: '20'
       - run: npm install -g specshield
-
       - name: Verify contract
         env:
           SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
         run: |
-          specshield contracts verify \\
-            --contract-id ${{ vars.PAYMENT_CONTRACT_ID }} \\
-            --base-url http://localhost:8080 \\
-            --provider-version ${{ github.sha }} \\
+          specshield contracts verify \
+            --contract-id ${{ vars.CONTRACT_ID }} \
+            --base-url http://localhost:8080 \
+            --provider-version ${{ github.sha }} \
             --env staging
-
       - name: Can I deploy?
         env:
           SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
         run: |
-          specshield contracts can-i-deploy \\
-            --provider payment-service \\
-            --version ${{ github.sha }} \\
+          specshield contracts can-i-deploy \
+            --provider payment-service \
+            --version ${{ github.sha }} \
             --env staging
 ```
 
@@ -740,22 +497,20 @@ jobs:
 
 ## Config File
 
-Create `.specshield.yml` in your project root to set default behavior:
+Create `.specshield.yml` in your project root:
 
 ```yaml
 failOnBreaking: true
-allowBreakingChanges: false
 severity: error
 
 ignore:
   - "DELETE /admin removed"
-  - "User.internal_id removed"
 
 remote:
   enabled: false
   url: "https://specshield.io/compare"
   timeout: 10000
-  apiKey: ""        # prefer env var or specshield login instead
+  # apiKey: ""  ← use env var instead
 ```
 
 CLI flags always override config file values.
@@ -770,17 +525,16 @@ specshield compare <base> <target> [options]
 
 | Option | Description |
 |---|---|
-| `--remote` | Use the SpecShield hosted compare API |
-| `--api-key <key>` | API token for remote mode (overrides env and stored config) |
-| `--remote-url <url>` | Override the hosted API base URL |
-| `--fail-on-breaking` | Exit code 1 if breaking changes are found |
+| `--remote` | Use the SpecShield hosted API |
+| `--api-key <key>` | API token |
+| `--fail-on-breaking` | Exit code 1 on breaking changes |
 | `--allow-breaking` | Override fail-on-breaking |
-| `--json` | Output machine-readable JSON |
-| `--output <file>` | Save result to a file |
-| `--ignore <change>` | Ignore a specific change string (repeatable) |
-| `--severity <level>` | Minimum severity: `info` / `warning` / `error` |
+| `--json` | Machine-readable JSON output |
+| `--output <file>` | Save result to file |
+| `--ignore <change>` | Ignore a specific change (repeatable) |
+| `--severity <level>` | `info` / `warning` / `error` |
 | `--config <path>` | Path to `.specshield.yml` |
-| `--timeout <ms>` | Request timeout for remote mode (default: 10000) |
+| `--timeout <ms>` | Request timeout for remote mode |
 
 ---
 
@@ -788,79 +542,32 @@ specshield compare <base> <target> [options]
 
 | Code | Meaning |
 |---|---|
-| `0` | Success — no blocking issues |
-| `1` | Breaking changes found and `--fail-on-breaking` is active |
-| `2` | Invalid input, missing token, config error, or runtime error |
+| `0` | Clean — no breaking changes |
+| `1` | Breaking changes found with `--fail-on-breaking` |
+| `2` | Config error, missing token, or runtime error |
 
 ---
 
-## CI/CD — GitHub Actions
-
-### Local compare (no token required)
-
-```yaml
-name: API Contract Check
-
-on:
-  pull_request:
-    branches: [main]
-
-jobs:
-  check-api-contract:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - run: npm install -g specshield
-
-      - name: Get base spec from main branch
-        run: git show origin/main:api/openapi.yaml > /tmp/base-spec.yaml
-
-      - name: Compare specs
-        run: |
-          specshield compare /tmp/base-spec.yaml api/openapi.yaml \\
-            --fail-on-breaking \\
-            --output spec-diff.json
+## License
 
-      - name: Upload diff report
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: spec-diff
-          path: spec-diff.json
-```
+MIT © Deepak Satyam
 
-### Remote compare (with SpecShield hosted API)
+---
 
-Add your API token as a GitHub Actions secret named `SPECSHIELD_API_KEY`, then:
+## Support
 
-```yaml
-      - name: Compare specs (remote)
-        env:
-          SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
-        run: |
-          specshield compare /tmp/base-spec.yaml api/openapi.yaml \\
-            --remote \\
-            --fail-on-breaking \\
-            --output spec-diff.json
-```
+Questions or issues?
 
-> **Note:** If your project generates its OpenAPI spec dynamically (e.g. Spring Boot, FastAPI), add a build step before the compare step to generate the spec from your code.
+- 📧 [admin@specshield.io](mailto:admin@specshield.io)
+- 🐛 [Open an issue on GitHub](https://github.com/specshield26/specshield-cli/issues)
+- 🌐 [specshield.io](https://specshield.io)
 
 ---
 
-## License
+<div align="center">
 
-MIT © Deepak Satyam
+**[⭐ Star on GitHub](https://github.com/specshield26/specshield-cli) · [📦 View on npm](https://www.npmjs.com/package/specshield) · [🚀 Create free account](https://specshield.io)**
 
----
-
-## Support
+*Stop finding out about API breakage from your users.*
 
-Questions or issues? Reach out at [admin@specshield.io](mailto:admin@specshield.io) or open an issue on GitHub.
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "CLI to compare OpenAPI/Swagger specs and detect breaking changes for CI/CD pipelines and local developer workflows.",
   "main": "src/cli.js",
   "bin": {