specshield 3.4.10 → 3.4.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,23 @@
1
1
  # SpecShield CLI changelog
2
2
 
3
+ ## Unreleased — usage-aware compare: "who does this change break?"
4
+
5
+ ### Added
6
+
7
+ - **`specshield usage import <logs...>`** — aggregates access logs (nginx/Apache combined
8
+ & common, AWS ALB, JSON lines; `.gz` and stdin) into `usage.json`: per endpoint × client
9
+ call counts, query-parameter names, first/last seen. Runs locally; stores no concrete
10
+ IDs, query values, IPs or bodies. `--spec`, `--base-path`, `--client ua|field:|extra:`
11
+ (with `hash:`), `--since`, `--append` (duplicate files skipped), `--format`.
12
+ - **`specshield usage show [file] [--spec]`** — top endpoints and clients; with `--spec`,
13
+ operations never called in the window and calls the spec doesn't document.
14
+ - **`compare --usage <file>`** — annotates breaking changes and warnings with the clients
15
+ that exercise them (exact for query parameters). Breaking changes with zero calls move to
16
+ `unusedBreakingChanges` and don't fail `--fail-on-breaking`, only when the usage covers
17
+ ≥ `--usage-min-days` (default 7), is ≤ 30 days old and matches the base spec.
18
+ Also `--usage-ignore-client`, `--no-usage-downgrade`, and a `usage:` block in
19
+ `.specshield.yml`. JSON output is unchanged unless `--usage` is given.
20
+
3
21
  ## 3.4.0 — 2026-07-29 — `govern` command (API governance in the CLI)
4
22
 
5
23
  ### Added
package/README.md CHANGED
@@ -9,6 +9,29 @@
9
9
 
10
10
  ▶️ **[Watch: SpecShield in 60 seconds](https://www.youtube.com/watch?v=7Tp502KN5R8)**
11
11
 
12
+ > **Contract Compatibility Testing · OpenAPI Diff · Breaking-Change Detection · `can-i-deploy` Deploy Gate · API Governance & Linting · Pact-File Ingest · Live-Traffic Capture · Spec-vs-Production Conformance · GitHub PR Checks**
13
+
14
+ ## Never ship a breaking change to your API consumers
15
+
16
+ **SpecShield™ is contract compatibility testing for APIs** — catch breaking changes before they reach your consumers, and gate every deploy with `can-i-deploy`. *(Contract compatibility testing is also known as bidirectional contract testing.)*
17
+
18
+ ```bash
19
+ npm install -g specshield
20
+ specshield compare base.yaml target.yaml --fail-on-breaking
21
+ ```
22
+
23
+ No account, no config, no broker to run or host. Language-agnostic. Local mode never uploads your specs.
24
+
25
+ What the CLI does:
26
+
27
+ 1. **Diff** two OpenAPI specs and fail CI on breaking changes. *(Free)*
28
+ 2. **Contract compatibility testing** with `can-i-deploy` — block a deploy that would break a consumer. *(Team)*
29
+ 3. **`govern`** — lint your spec against OWASP + design rules and gate the PR on violations. *(Team)*
30
+ 4. **`bdct capture from-har`** — turn recorded traffic into an accurate consumer contract (no Pact DSL). *(Free)*
31
+ 5. **`bdct verify-provider`** — prove the running provider actually matches its OpenAPI spec. *(Free)*
32
+
33
+ ---
34
+
12
35
  ## Contents
13
36
 
14
37
  **Get started**
@@ -16,16 +39,16 @@
16
39
 
17
40
  **Why SpecShield**
18
41
  - [The Problem](#the-problem) · [The Solution](#the-solution) · [See It in Action](#see-it-in-action) · [Use Cases](#use-cases)
19
- - [Local vs Cloud](#local-vs-cloud) · [vs. Alternatives](#vs-alternatives) · [Pricing](#pricing)
42
+ - [vs. Alternatives](#vs-alternatives) · [Pricing](#pricing)
20
43
 
21
44
  **Commands — local & hosted compare**
22
- - [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)
45
+ - [Local Compare](#local-compare) · [**Who does a change break? (usage-aware compare)**](#who-does-a-change-break--usage-aware-compare) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
23
46
 
24
47
  **Governance — lint & gate**
25
48
  - [`specshield govern`](#governance--lint-a-spec-and-gate-the-pr)
26
49
 
27
50
  **Contract Compatibility Testing — the `bdct` commands**
28
- - [Overview & full command reference](#bi-directional-contract-testing-bdct)
51
+ - [Overview & full command reference](#contract-compatibility-testing--the-bdct-commands)
29
52
  - [`bdct capture from-har` — HAR → consumer contract](#bdct-capture-from-har--turn-real-traffic-into-a-consumer-contract)
30
53
  - [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)
31
54
  - [`bdct verify-provider` — spec-vs-production conformance](#bdct-verify-provider--does-your-live-provider-actually-match-its-spec)
@@ -41,38 +64,14 @@
41
64
 
42
65
  ---
43
66
 
44
- > **Contract Compatibility Testing · OpenAPI Diff · Breaking-Change Detection · `can-i-deploy` Deploy Gate · API Governance & Linting · Pact-File Ingest · Live-Traffic Capture · Spec-vs-Production Conformance · GitHub PR Checks**
45
-
46
- ---
47
-
48
- ## Never ship a breaking change to your API consumers
49
-
50
- **SpecShield™ is contract compatibility testing for APIs** — catch breaking changes before they reach your consumers, and gate every deploy with `can-i-deploy`. *(Contract compatibility testing is also known as bidirectional contract testing.)*
51
-
52
- It's the one CLI that does five things to keep your API safe:
53
-
54
- 1. **Diff** two OpenAPI specs and fail CI on breaking changes.
55
- 2. **Contract compatibility testing** with `can-i-deploy` — block a deploy that would break a consumer.
56
- 3. **`govern`** — lint your spec against OWASP + design rules and gate the PR on violations.
57
- 4. **`bdct capture from-har`** — turn recorded traffic into an accurate consumer contract (no Pact DSL).
58
- 5. **`bdct verify-provider`** — prove the running provider actually matches its OpenAPI spec.
59
-
60
- ```
61
- OpenAPI diff + contract compatibility checks + API governance + HAR → consumer contract + spec-vs-production conformance — in one CLI.
62
- ```
63
-
64
- No broker. No Pact DSL. Language-agnostic. Works in 30 seconds. Local mode never uploads your specs.
65
-
66
- ---
67
-
68
- ## One platform, five ways to run it
67
+ ## Where it runs
69
68
 
70
69
  This CLI is one surface of the **SpecShield™ platform**. The same contract-compatibility and governance engine powers every entry point — they share one project file (`.specshield.yml`), one API key, and one set of audit events. Adopt the one that fits your stack today and grow into the others:
71
70
 
72
71
  | Surface | Best for |
73
72
  |---|---|
74
73
  | **GitHub App** — [github.com/apps/specshield-deploy-gate](https://github.com/apps/specshield-deploy-gate) | Zero-config PR checks. Install once; every PR gets a check run and a diff comment. |
75
- | **GitHub Action** — [`specshield-io/bdct-action@v1`](https://github.com/marketplace/actions/specshield-bdct) | Pinned, reproducible BDCT + governance gate in any GitHub workflow. |
74
+ | **GitHub Action** — [`specshield-io/bdct-action@v1`](https://github.com/marketplace/actions/specshield-bdct) | Pinned, reproducible contract-compatibility + governance gate in any GitHub workflow. |
76
75
  | **CLI** *(this package)* | Any CI — GitLab, Jenkins, CircleCI, Bitbucket, Drone — or your laptop. |
77
76
  | **IntelliJ plugin** — [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/33137-specshield) | Inline spec findings, one-click auto-fixes, compare & explain — inside IntelliJ IDEA, WebStorm, PyCharm and more. |
78
77
  | **MCP server** — [`specshield-mcp-server`](https://github.com/specshield-io/specshield-mcp-server) | Give Claude, Cursor, and other AI agents the same deploy gate. |
@@ -94,6 +93,8 @@ Plus a hosted **dashboard** at [specshield.io](https://specshield.io) — compat
94
93
  - A required field changes — partner integrations fail at 2am.
95
94
  - You find out from an angry customer, not from CI.
96
95
 
96
+ It's rarely guarded against: in [our survey of public repos that publish OpenAPI specs](https://specshield.io/blog/95-percent-no-compatibility-gate), **95% had no breaking-change check in CI at all.**
97
+
97
98
  Manual review doesn't catch it. Integration tests run too late.
98
99
  **You need a contract between your services — and something that enforces it on every PR and every deploy.**
99
100
 
@@ -171,9 +172,9 @@ npm install -g specshield
171
172
  specshield compare base.yaml target.yaml --fail-on-breaking
172
173
  ```
173
174
 
174
- Works with any OpenAPI 3.x YAML or JSON.
175
+ Works with OpenAPI 3.0 / 3.1 and Swagger 2.0, in YAML or JSON.
175
176
 
176
- **For BDCT**, run the wizard once and never re-type the same flags again:
177
+ **For the `bdct` commands**, run the wizard once and never re-type the same flags again:
177
178
 
178
179
  ```bash
179
180
  specshield init
@@ -190,7 +191,9 @@ specshield bdct can-i-deploy --version $GITHUB_SHA
190
191
 
191
192
  ---
192
193
 
193
- ## A Real-World Story
194
+ ## Example: how it plays out
195
+
196
+ *An illustrative scenario:*
194
197
 
195
198
  > The `payment-service` team merged a change that renamed `status` to
196
199
  > `paymentStatus`. The `checkout-ui` team wasn't notified.
@@ -224,30 +227,6 @@ specshield bdct can-i-deploy --version $GITHUB_SHA
224
227
 
225
228
  ---
226
229
 
227
- ## Local vs Cloud
228
-
229
- | Feature | Local (Free) | Team | Enterprise |
230
- |---|---|---|---|
231
- | Compare two spec files | ✅ | ✅ | ✅ |
232
- | Breaking change detection | ✅ | ✅ | ✅ |
233
- | JSON / human output | ✅ | ✅ | ✅ |
234
- | Fail CI on breaking change | ✅ | ✅ | ✅ |
235
- | **`bdct capture from-har`** | ✅ | ✅ | ✅ |
236
- | **`bdct verify-provider`** | ✅ | ✅ | ✅ |
237
- | `specshield history` — compare timeline | ❌ | ✅ | ✅ |
238
- | `specshield share` — public report URLs | ❌ | ✅ | ✅ |
239
- | Hosted dashboard | ❌ | ✅ | ✅ |
240
- | GitHub App PR checks | ❌ | ✅ | ✅ |
241
- | BDCT consumer registry + can-i-deploy gate | ❌ | ✅ | ✅ |
242
- | BDCT compatibility matrix | ❌ | ✅ | ✅ |
243
- | Team workspace + audit log + RBAC | ❌ | ✅ | ✅ |
244
- | Slack notifications | ❌ | ✅ | ✅ |
245
- | SAML SSO, SCIM, on-prem | ❌ | ❌ | ✅ |
246
-
247
- > **The local-only commands are first-class.** `compare`, `bdct capture from-har`, and `bdct verify-provider` all run entirely in your CI — your spec text never leaves your infrastructure.
248
-
249
- ---
250
-
251
230
  # Commands
252
231
 
253
232
  ## Local Compare
@@ -271,11 +250,81 @@ specshield compare base.yaml target.yaml --output result.json
271
250
  specshield compare base.yaml target.yaml --ignore "DELETE /admin removed" --fail-on-breaking
272
251
  ```
273
252
 
253
+ ## Who does a change break? — usage-aware compare
254
+
255
+ A spec diff tells you **what** changed. Your access logs know **who** still calls it.
256
+ `specshield usage` joins the two, so every breaking change shows the clients it would
257
+ break — and a removal that nobody calls stops failing the build.
258
+
259
+ ```text
260
+ ✖ BREAKING CHANGES
261
+ ● DELETE /orders/{orderId}/receipt method was removed
262
+ ↳ impact: 1 client · 134 calls · last seen 72 min ago
263
+ MyShop-iOS/5.2 100% of calls 134 · last seen 72 min ago
264
+ ● Parameter "expand" (query) was removed from GET /orders
265
+ ↳ impact: 1 client · 200 calls sending "expand" · last seen 2 h ago
266
+ okhttp/4.12 33% of calls 200 · last seen 2 h ago
267
+
268
+ ✔ BREAKING BUT UNUSED — safe to ship
269
+ 0 calls between 2026-10-05 and 2026-10-25; these do not fail the build
270
+ ○ GET /legacy-report was removed
271
+ ```
272
+
273
+ **1. Turn access logs into a usage summary** (runs locally — raw logs never leave the machine):
274
+
275
+ ```bash
276
+ specshield usage import /var/log/nginx/access.log* --spec api/openapi.yaml
277
+ # → usage.json: per endpoint × client, call counts, query-parameter names, first/last seen
278
+ ```
279
+
280
+ - **Formats:** nginx/Apache combined & common, AWS ALB, and JSON lines (nginx JSON
281
+ `log_format`, Kong file-log, API Gateway, Envoy/Traefik, ECS). Auto-detected; `.gz`
282
+ files and stdin (`-`) work. Force one with `--format combined|alb|json`.
283
+ - **Clients** are identified by User-Agent by default (`MyShop-iOS/5.2.1` → `MyShop-iOS/5.2`).
284
+ Use a better signal if you log one: `--client field:consumer.username` (JSON logs),
285
+ `--client extra:1` (first quoted field after the User-Agent in combined logs), and prefix
286
+ `hash:` for API keys — `--client hash:extra:1` stores a one-way hash, never the key.
287
+ - **Privacy:** only aggregates are stored — path templates, counts, timestamps, and query
288
+ parameter *names*. No IDs from concrete paths, no query values, no IPs, no bodies.
289
+ - `--spec` maps `/v1/orders/123` onto `/orders/{orderId}` exactly as your spec defines it
290
+ (base paths from `servers` / `basePath`, or `--base-path`). Without it, IDs are guessed.
291
+ - Add more days later with `--append` (a file imported twice is detected and skipped);
292
+ limit the window with `--since 30d`.
293
+
294
+ **2. Compare with impact:**
295
+
296
+ ```bash
297
+ specshield compare base.yaml target.yaml --usage usage.json --fail-on-breaking
298
+ ```
299
+
300
+ - **Endpoint and method removals, body/response field changes** → the clients calling that
301
+ operation. Access logs don't show which response fields a client reads, so for field
302
+ changes this is "clients that may be affected", and the report says so.
303
+ - **Query parameters** are judged exactly: a removed parameter affects only clients that
304
+ *send* it; a parameter that became required affects only clients that *omit* it.
305
+ - **Zero calls → "breaking but unused"**: listed separately and excluded from
306
+ `--fail-on-breaking`. SpecShield only does this when the evidence is good enough — at
307
+ least `--usage-min-days` (default 7) of logs, the newest no older than 30 days, and calls
308
+ that actually match the base spec. Otherwise the change stays breaking and the report
309
+ says why. `--no-usage-downgrade` keeps everything breaking and only annotates.
310
+ - Leave health checks and bots out: `--usage-ignore-client 'kube-probe/*' --usage-ignore-client healthcheck`.
311
+ - `--json` adds `impact` to each change, plus `unusedBreakingChanges`, `summary.unusedBreaking`
312
+ and a `usage` block. Without `--usage` the JSON is unchanged.
313
+
314
+ **3. Find dead and undocumented endpoints:**
315
+
316
+ ```bash
317
+ specshield usage show usage.json --spec api/openapi.yaml
318
+ # NEVER CALLED IN THIS WINDOW → candidates for deprecation
319
+ # CALLED BUT NOT IN THE SPEC → shadow endpoints your spec is missing
320
+ ```
321
+
274
322
  ## Remote Compare
275
323
 
276
324
  Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
277
325
  heavy comparison off your CI runner and for cross-validating against the
278
- exact engine the dashboard uses. Requires a free account.
326
+ exact engine the dashboard uses. Requires an API key from a free account —
327
+ without one the CLI exits with code `2` (`No API key found`).
279
328
 
280
329
  ```bash
281
330
  specshield compare base.yaml target.yaml --remote
@@ -283,10 +332,9 @@ specshield compare base.yaml target.yaml --remote --fail-on-breaking
283
332
  specshield compare base.yaml target.yaml --remote --json --output result.json
284
333
  ```
285
334
 
286
- > **History note:** with an API key set (run `specshield login`, or pass
287
- > `--api-key` / `SPECSHIELD_API_KEY`), `--remote` saves each comparison to
288
- > your history and the response includes a `historyId` you can hand to
289
- > `specshield share`. Without a key the diff still runs — it just isn't saved.
335
+ > **History note:** set your key with `specshield login`, `--api-key`, or
336
+ > `SPECSHIELD_API_KEY`. Each `--remote` comparison is saved to your history,
337
+ > and the response includes a `historyId` you can hand to `specshield share`.
290
338
 
291
339
  ## Comparison History
292
340
 
@@ -427,13 +475,15 @@ Run it in CI right after your build:
427
475
 
428
476
  ---
429
477
 
430
- # Bi-Directional Contract Testing (BDCT)
478
+ # Contract Compatibility Testing — the `bdct` commands
431
479
 
432
480
  **Compatibility without Pact's broker overhead or DSL.**
433
481
 
482
+ > **Plan:** the registry commands — `publish-provider`, `publish-consumer`, `verify`, `can-i-deploy`, `matrix` and the `list*` commands — need a **Team** plan — on Free the server rejects them with a paid-plan error (exit code `2`). `capture from-har` and `verify-provider` are free and run fully locally. **[See plans →](https://specshield.io/pricing)**
483
+
434
484
  Both sides publish what they have — provider publishes its OpenAPI spec, consumer publishes either an OpenAPI subset *or* a Pact JSON file — and SpecShield's engine verifies that every endpoint/field the consumer relies on is satisfied by the provider. `can-i-deploy` then gates the deploy.
435
485
 
436
- ### How BDCT Works
486
+ ### How it works
437
487
 
438
488
  1. Consumer publishes a contract (OpenAPI subset *or* Pact JSON).
439
489
  2. Provider publishes its full OpenAPI spec.
@@ -584,7 +634,7 @@ specshield bdct list-consumers --org acme-store --consumer checkout-ui
584
634
  specshield bdct list --org acme-store --provider payment-service --env production
585
635
  ```
586
636
 
587
- ### Full BDCT Workflow
637
+ ### Full workflow
588
638
 
589
639
  ```bash
590
640
  # 1. Provider publishes spec on every release
@@ -604,9 +654,9 @@ specshield bdct can-i-deploy \
604
654
  --version v2.1.0 --env production
605
655
  ```
606
656
 
607
- ### BDCT JSON Output
657
+ ### JSON output
608
658
 
609
- All BDCT commands support `--json` for CI parsing:
659
+ All `bdct` commands support `--json` for CI parsing:
610
660
 
611
661
  ```bash
612
662
  specshield bdct can-i-deploy --org acme-store --service payment-service --version v2.1.0 --json
@@ -630,7 +680,7 @@ specshield bdct can-i-deploy --org acme-store --service payment-service --versio
630
680
 
631
681
  # `bdct capture from-har` — turn real traffic into a consumer contract
632
682
 
633
- **This is the feature that makes BDCT actually work for normal teams.**
683
+ **This is the feature that makes contract testing actually work for normal teams.**
634
684
  Pact requires every consumer team to learn a DSL, instrument their tests,
635
685
  and run a broker. SpecShield asks for something they already have: a
636
686
  recording of an HTTP test run, in the universal HAR format that every
@@ -658,7 +708,7 @@ integration" and "we proved the integration."
658
708
  ```
659
709
 
660
710
  Step 1 already happens in your team — you're just saving the file. Step 2
661
- is one CLI command. Step 3 is the BDCT registry you publish to.
711
+ is one CLI command. Step 3 is the contract registry you publish to.
662
712
 
663
713
  ---
664
714
 
@@ -676,118 +726,10 @@ project. You almost never have to write recorder code yourself.
676
726
  | **[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 |
677
727
  | **[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 |
678
728
 
679
- **Recipes follow** — keep reading for the exact commands per tool, then jump
680
- to Step 2 (the capture command, which is identical regardless of recorder).
681
-
682
- ### 1a. Chrome / Firefox / Edge DevTools (zero code — best for frontend)
683
-
684
- 1. Open the page that calls your API in the browser.
685
- 2. Open DevTools (`F12` / `Cmd+Opt+I`) → **Network** tab.
686
- 3. Click the 🚫 button to clear, then reload the page and click through the
687
- flows you want to record.
688
- 4. Right-click anywhere in the request list → **Save all as HAR with
689
- content** → save as `traffic.har`.
690
-
691
- That's the entire recording. The file is byte-compatible with everything
692
- SpecShield does.
693
-
694
- > **Safari note:** Safari's "Export HAR" is under the Develop menu →
695
- > *Export…* in the Network tab; it produces the same format.
696
-
697
- ### 1b. Playwright (best for teams with UI tests)
698
-
699
- Add one option to your `playwright.config.js`:
700
-
701
- ```js
702
- // playwright.config.js
703
- const path = require('path');
704
- module.exports = {
705
- testDir: './tests',
706
- use: {
707
- baseURL: 'https://staging.acme.com',
708
- recordHar: { path: path.resolve(__dirname, 'traffic.har'), mode: 'full', content: 'embed' },
709
- },
710
- };
711
- ```
712
-
713
- Run your tests as usual:
714
-
715
- ```bash
716
- npx playwright test
717
- # → writes traffic.har on context close
718
- ```
719
-
720
- The HAR will contain every HTTP call the browser made during the test —
721
- HTML, JS, images, and the API JSON. The `--onlyJson` default in Step 2
722
- filters out the noise automatically.
723
-
724
- > Need the HAR file flushed **per test**? Create the context explicitly in
725
- > your test and call `await context.close()` at the end. A runnable
726
- > copy-paste starter lives in [`examples/playwright-har/`](examples/playwright-har/)
727
- > of this repo — clone, `npm install`, `npx playwright install chromium`,
728
- > `npm test` produces `traffic.har` against the public JSONPlaceholder
729
- > sandbox so you can verify the toolchain works before pointing it at your
730
- > own provider.
731
-
732
- ### 1c. Cypress
733
-
734
- ```bash
735
- npm i -D @neuralegion/cypress-har-generator
736
- ```
737
-
738
- ```js
739
- // cypress.config.js
740
- const { install } = require('@neuralegion/cypress-har-generator');
741
- module.exports = { e2e: { setupNodeEvents(on, config) { install(on); return config; } } };
742
-
743
- // cypress/support/e2e.js
744
- beforeEach(() => cy.recordHar());
745
- afterEach(() => cy.saveHar({ outDir: './har-out' }));
746
- ```
747
-
748
- Run `npx cypress run` and the HAR for each spec lands in `har-out/`.
749
-
750
- ### 1d. mitmproxy (best for backend service-to-service)
751
-
752
- When the consumer is a backend service (no browser), point it through
753
- mitmproxy in your integration-test env. No consumer code change.
754
-
755
- ```bash
756
- # Install once
757
- brew install mitmproxy # macOS — also available via pip and apt
758
-
759
- # Start the proxy and tell it to dump HAR
760
- mitmdump --set hardump=traffic.har --listen-port 8080
761
-
762
- # In another terminal: run your tests with HTTPS_PROXY pointing at it
763
- HTTPS_PROXY=http://localhost:8080 HTTP_PROXY=http://localhost:8080 \
764
- ./run-integration-tests.sh
765
-
766
- # Ctrl-C mitmdump when done — traffic.har is on disk
767
- ```
768
-
769
- The `hardump` add-on is built into mitmproxy ≥ 9.0. For TLS hosts you'll
770
- need to trust mitmproxy's CA in your test JVM/runtime (see the
771
- [mitmproxy CA docs](https://docs.mitmproxy.org/stable/concepts-certificates/));
772
- in many test environments it's a single env var
773
- (`NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, or a
774
- JVM `cacerts` import).
775
-
776
- ### 1e. Postman / Insomnia / Bruno
777
-
778
- Run the request (or a whole collection runner). Right-click the response
779
- → **Save Response as HAR**. Repeat for each request you want included,
780
- then either keep them as separate `.har` files (pass `--in` once per file
781
- via a loop in CI) or merge them with any HAR-merge tool.
782
-
783
- ### 1f. k6 load test (bonus — recording while load-testing)
784
-
785
- ```bash
786
- k6 run --out har=traffic.har script.js
787
- ```
788
-
789
- k6 emits a HAR alongside its load metrics. Same file works with
790
- `bdct capture from-har`.
729
+ **Step-by-step recipes for each recorder** (DevTools, Playwright, Cypress,
730
+ mitmproxy, Postman, k6) are in
731
+ [`docs/har-recipes.md`](https://github.com/specshield-io/specshield-cli/blob/main/docs/har-recipes.md).
732
+ The Step 2 command is identical whichever recorder you use.
791
733
 
792
734
  ---
793
735
 
@@ -869,7 +811,7 @@ specshield bdct can-i-deploy \
869
811
  # exit 0 = safe; exit 1 = a verification says NO and the deploy is blocked
870
812
  ```
871
813
 
872
- Full BDCT command reference is in the [Bi-Directional Contract Testing](#bi-directional-contract-testing-bdct)
814
+ Full command reference is in the [Contract Compatibility Testing](#contract-compatibility-testing--the-bdct-commands)
873
815
  section above.
874
816
 
875
817
  ---
@@ -971,26 +913,11 @@ syntax changes.
971
913
 
972
914
  ---
973
915
 
974
- ## Why this is the most valuable piece of the CLI
975
-
976
- Every other contract-testing product on the market asks the consumer team
977
- to **change their code** — adopt a DSL, instrument their tests, run a
978
- broker. That tax is why most teams that "should" be doing contract testing
979
- aren't.
980
-
981
- `bdct capture from-har` removes the tax. Your team's existing test run is
982
- already the contract; the CLI just converts the format. The HAR-capture →
983
- publish → can-i-deploy loop is what turns "we have OpenAPI specs in a
984
- folder" into "no provider PR merges if it would break a deployed consumer"
985
- — with measurable enforcement, in one CI step, and no per-language SDK.
986
-
987
- ---
988
-
989
916
  # `bdct verify-provider` — does your live provider actually match its spec?
990
917
 
991
918
  **Active spec-vs-production conformance — Dredd-style, in CI.**
992
919
 
993
- Most teams trust the provider's OpenAPI as the source of truth and never check whether the running service actually matches it. SpecShield's compatibility engine for BDCT is only as accurate as that trust — so `verify-provider` closes the loop by **firing probes derived from the spec at a running endpoint** (staging, usually) and validating every response body against the spec's schema for its status code.
920
+ Most teams trust the provider's OpenAPI as the source of truth and never check whether the running service actually matches it. SpecShield's compatibility engine is only as accurate as that trust — so `verify-provider` closes the loop by **firing probes derived from the spec at a running endpoint** (staging, usually) and validating every response body against the spec's schema for its status code.
994
921
 
995
922
  Catches things like: the spec says `status ∈ {paid, pending, refunded}` but the live API sometimes returns `partially_refunded`. Or a field documented as `required` is sometimes missing. Or a `format: uuid` field actually contains a numeric ID.
996
923
 
@@ -1105,7 +1032,7 @@ jobs:
1105
1032
  ### On Push — Publish provider spec + gate the deploy
1106
1033
 
1107
1034
  ```yaml
1108
- name: BDCT Publish & Deploy Gate
1035
+ name: Publish Provider & Deploy Gate
1109
1036
  on:
1110
1037
  push:
1111
1038
  branches: [main]
@@ -1170,7 +1097,7 @@ jobs:
1170
1097
  | | **SpecShield** | **Pact / PactFlow** (SmartBear) | **oasdiff** | **Specmatic** / **Microcks** (OSS) |
1171
1098
  |---|---|---|---|---|
1172
1099
  | OpenAPI-native | ✅ | partial (Pact DSL) | ✅ | ✅ |
1173
- | No broker required | ✅ | ❌ (Pact Broker) | ✅ | ✅ |
1100
+ | No broker to run or host | ✅ | ❌ (Pact Broker or paid PactFlow) | ✅ | ✅ |
1174
1101
  | Bi-directional contract testing | ✅ | ✅ (Pactflow paid) | ❌ | partial |
1175
1102
  | Breaking-change detection | ✅ | ❌ | ✅ | ❌ |
1176
1103
  | `can-i-deploy` gating | ✅ | ✅ (broker) | ❌ | ❌ |
@@ -1191,10 +1118,13 @@ jobs:
1191
1118
  | Plan | Price | What's included |
1192
1119
  |---|---|---|
1193
1120
  | **Free** | $0 forever | Local compare · `bdct capture from-har` · `bdct verify-provider` · public web diff · 7-day compare history · 1 GitHub App PR check |
1194
- | **Team** | $89/mo ($75 annual) | Everything in Free + consumer registry · enforced `can-i-deploy` gate · audit trail · BDCT compatibility matrix · Slack alerts · team workspace + RBAC · priority email support |
1195
- | **Enterprise** | Talk to us | Everything in Team + SAML SSO · SCIM · on-prem / private-cloud · advanced RBAC + audit-log export · dedicated onboarding + SLA |
1121
+ | **Team** | $89/mo, or $900/yr ($75/mo) · up to 10 users | Everything in Free + consumer registry · enforced `can-i-deploy` gate · compatibility matrix · `govern` governance gate · audit trail · Slack alerts · team workspace + RBAC · priority email support |
1122
+ | **Enterprise** | Custom · unlimited users | Everything in Team + SSO and on-prem / private-cloud (on request) · advanced RBAC + audit-log export · dedicated onboarding + SLA |
1196
1123
 
1197
- No credit card for the free plan. **[Get started free →](https://specshield.io)** · For Enterprise: [sales@specshield.io](mailto:sales@specshield.io).
1124
+ Prices exclude VAT/GST, added at checkout where applicable. No credit card for the free plan.
1125
+
1126
+ > **The local-only commands are first-class.** `compare`, `bdct capture from-har`, and `bdct verify-provider` run entirely in your CI on the Free plan — your spec text never leaves your infrastructure.
1127
+ **[Get started free →](https://specshield.io)** · For Enterprise: [sales@specshield.io](mailto:sales@specshield.io).
1198
1128
 
1199
1129
  ---
1200
1130
 
@@ -1206,7 +1136,7 @@ Run once at the root of your project. The wizard:
1206
1136
  2. Detects your service name (`package.json`, `pyproject.toml`, `pom.xml`, `go.mod`, `Cargo.toml`, or directory name).
1207
1137
  3. Detects your git branch and suggests `production` for `main`/`master`, `staging` otherwise.
1208
1138
  4. Asks whether this project is a provider, a consumer, or both.
1209
- 5. Asks for your org key (autocompletes from your account if signed in).
1139
+ 5. Asks for your org key — copy it from the dashboard at [specshield.io/account/team](https://specshield.io/account/team).
1210
1140
  6. Validates / stores your API key.
1211
1141
  7. Writes **`.specshield.yml`** and (optionally) a starter **`.github/workflows/specshield-bdct.yml`** using [`specshield-io/bdct-action@v1`](https://github.com/marketplace/actions/specshield-bdct).
1212
1142
 
@@ -1278,7 +1208,7 @@ specshield init --no-interactive \
1278
1208
  | `--consumer-provider <name>` | The provider this consumer talks to. |
1279
1209
  | `--contract <path>` | Path to the consumer contract (OpenAPI or Pact JSON). |
1280
1210
  | `--format <fmt>` | Consumer contract format: `OPENAPI` (default) or `PACT`. |
1281
- | `--env <environment>` | Default environment for BDCT operations. |
1211
+ | `--env <environment>` | Default environment for `bdct` operations. |
1282
1212
  | `--write-workflow` | Also write a starter GitHub Actions workflow. |
1283
1213
 
1284
1214
  > **What is _not_ written into `.specshield.yml`:** your API key. It's stored in `~/.specshield/config.json` (set by `specshield login`) or read from `SPECSHIELD_API_KEY` in CI. The project file is committed; never commit a secret into it.
@@ -1340,13 +1270,20 @@ severity: error # info | warning | error
1340
1270
  ignore:
1341
1271
  - "DELETE /admin removed" # match by substring; repeatable
1342
1272
 
1273
+ # Usage-aware compare (same as --usage …; see "Who does a change break?").
1274
+ # usage:
1275
+ # file: usage.json
1276
+ # ignoreClients: ["kube-probe/*"]
1277
+ # minDays: 7
1278
+ # downgrade: true
1279
+
1343
1280
  # Hosted compare (set --remote on the CLI to override).
1344
1281
  remote:
1345
1282
  enabled: false
1346
1283
  url: https://specshield.io/compare
1347
1284
  timeout: 10000
1348
1285
 
1349
- # BDCT defaults (used by every `specshield bdct …` subcommand).
1286
+ # `bdct` defaults (used by every `specshield bdct …` subcommand).
1350
1287
  bdct:
1351
1288
  org: acme-pay
1352
1289
  environment: staging
@@ -1370,7 +1307,7 @@ github:
1370
1307
  commentOnPr: true
1371
1308
  ```
1372
1309
 
1373
- With this file, BDCT commands collapse to `--version`:
1310
+ With this file, `bdct` commands collapse to `--version`:
1374
1311
 
1375
1312
  ```bash
1376
1313
  specshield bdct publish-provider --version $GITHUB_SHA
@@ -1394,9 +1331,14 @@ specshield compare <base> <target> [options]
1394
1331
  | `--json` | Machine-readable JSON output |
1395
1332
  | `--output <file>` | Save result to file |
1396
1333
  | `--ignore <change>` | Ignore a specific change (repeatable) |
1397
- | `--severity <level>` | `info` / `warning` / `error` |
1334
+ | `--severity <level>` | Minimum severity shown: `info` / `warning` / `error` (default `info`) |
1398
1335
  | `--config <path>` | Path to `.specshield.yml` |
1399
- | `--timeout <ms>` | Request timeout for remote mode |
1336
+ | `--remote-url <url>` | Override the hosted API base URL |
1337
+ | `--usage <file>` | `usage.json` from `specshield usage import` — show which clients each breaking change affects |
1338
+ | `--usage-ignore-client <pattern>` | Leave a client out of the impact (repeatable; `*` globs, otherwise substring) |
1339
+ | `--usage-min-days <n>` | Days of usage needed before an unused breaking change stops failing the build (default `7`) |
1340
+ | `--no-usage-downgrade` | Annotate impact only; keep unused breaking changes breaking |
1341
+ | `--timeout <ms>` | Request timeout for remote mode (default `10000`) |
1400
1342
 
1401
1343
  ```bash
1402
1344
  specshield history [options]
@@ -1417,6 +1359,17 @@ specshield share <reportId | base.yaml target.yaml> [options]
1417
1359
  | `--expires <days>` | Make the link expire after N days (default: never) |
1418
1360
  | `--api-key <key>` | Override stored API key |
1419
1361
 
1362
+ ```bash
1363
+ specshield whoami [options] # show the signed-in account
1364
+ specshield logout # remove the stored API key
1365
+ ```
1366
+
1367
+ | Option (`whoami`) | Description |
1368
+ |---|---|
1369
+ | `--api-token <key>` | Override stored / env API token for this call |
1370
+ | `--server <url>` | Override SpecShield server URL |
1371
+ | `--json` | Machine-readable JSON output |
1372
+
1420
1373
  ```bash
1421
1374
  specshield govern <spec> [options]
1422
1375
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specshield",
3
- "version": "3.4.10",
3
+ "version": "3.4.12",
4
4
  "description": "Contract compatibility testing for APIs — catch breaking OpenAPI changes before they reach your consumers, with can-i-deploy deploy gating and GitHub PR checks. (a.k.a. bidirectional contract testing.)",
5
5
  "main": "src/cli.js",
6
6
  "homepage": "https://specshield.io",
package/src/cli.js CHANGED
@@ -11,6 +11,7 @@ const governCommand = require('./commands/govern');
11
11
  const historyCommand = require('./commands/history');
12
12
  const shareCommand = require('./commands/share');
13
13
  const whoamiCommand = require('./commands/whoami');
14
+ const usageCommand = require('./commands/usage');
14
15
 
15
16
  const program = new Command();
16
17
 
@@ -32,6 +33,7 @@ program.addCommand(governCommand);
32
33
  program.addCommand(historyCommand);
33
34
  program.addCommand(shareCommand);
34
35
  program.addCommand(whoamiCommand);
36
+ program.addCommand(usageCommand);
35
37
 
36
38
  program.parseAsync(process.argv).catch((err) => {
37
39
  const logger = require('./utils/logger');