specshield 3.4.9 → 3.4.11

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.
Files changed (2) hide show
  1. package/README.md +84 -207
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -5,6 +5,33 @@
5
5
  [![license](https://img.shields.io/badge/license-MIT-blue)](#license)
6
6
  [![node](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org)
7
7
 
8
+ [![SpecShield in 60 seconds — watch on YouTube](https://img.youtube.com/vi/7Tp502KN5R8/maxresdefault.jpg)](https://www.youtube.com/watch?v=7Tp502KN5R8)
9
+
10
+ ▶️ **[Watch: SpecShield in 60 seconds](https://www.youtube.com/watch?v=7Tp502KN5R8)**
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
+
8
35
  ## Contents
9
36
 
10
37
  **Get started**
@@ -12,7 +39,7 @@
12
39
 
13
40
  **Why SpecShield**
14
41
  - [The Problem](#the-problem) · [The Solution](#the-solution) · [See It in Action](#see-it-in-action) · [Use Cases](#use-cases)
15
- - [Local vs Cloud](#local-vs-cloud) · [vs. Alternatives](#vs-alternatives) · [Pricing](#pricing)
42
+ - [vs. Alternatives](#vs-alternatives) · [Pricing](#pricing)
16
43
 
17
44
  **Commands — local & hosted compare**
18
45
  - [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)
@@ -21,7 +48,7 @@
21
48
  - [`specshield govern`](#governance--lint-a-spec-and-gate-the-pr)
22
49
 
23
50
  **Contract Compatibility Testing — the `bdct` commands**
24
- - [Overview & full command reference](#bi-directional-contract-testing-bdct)
51
+ - [Overview & full command reference](#contract-compatibility-testing--the-bdct-commands)
25
52
  - [`bdct capture from-har` — HAR → consumer contract](#bdct-capture-from-har--turn-real-traffic-into-a-consumer-contract)
26
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)
27
54
  - [`bdct verify-provider` — spec-vs-production conformance](#bdct-verify-provider--does-your-live-provider-actually-match-its-spec)
@@ -37,38 +64,14 @@
37
64
 
38
65
  ---
39
66
 
40
- > **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**
41
-
42
- ---
43
-
44
- ## Never ship a breaking change to your API consumers
45
-
46
- **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.)*
47
-
48
- It's the one CLI that does five things to keep your API safe:
49
-
50
- 1. **Diff** two OpenAPI specs and fail CI on breaking changes.
51
- 2. **Contract compatibility testing** with `can-i-deploy` — block a deploy that would break a consumer.
52
- 3. **`govern`** — lint your spec against OWASP + design rules and gate the PR on violations.
53
- 4. **`bdct capture from-har`** — turn recorded traffic into an accurate consumer contract (no Pact DSL).
54
- 5. **`bdct verify-provider`** — prove the running provider actually matches its OpenAPI spec.
55
-
56
- ```
57
- OpenAPI diff + contract compatibility checks + API governance + HAR → consumer contract + spec-vs-production conformance — in one CLI.
58
- ```
59
-
60
- No broker. No Pact DSL. Language-agnostic. Works in 30 seconds. Local mode never uploads your specs.
61
-
62
- ---
63
-
64
- ## One platform, five ways to run it
67
+ ## Where it runs
65
68
 
66
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:
67
70
 
68
71
  | Surface | Best for |
69
72
  |---|---|
70
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. |
71
- | **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. |
72
75
  | **CLI** *(this package)* | Any CI — GitLab, Jenkins, CircleCI, Bitbucket, Drone — or your laptop. |
73
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. |
74
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. |
@@ -90,6 +93,8 @@ Plus a hosted **dashboard** at [specshield.io](https://specshield.io) — compat
90
93
  - A required field changes — partner integrations fail at 2am.
91
94
  - You find out from an angry customer, not from CI.
92
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
+
93
98
  Manual review doesn't catch it. Integration tests run too late.
94
99
  **You need a contract between your services — and something that enforces it on every PR and every deploy.**
95
100
 
@@ -167,9 +172,9 @@ npm install -g specshield
167
172
  specshield compare base.yaml target.yaml --fail-on-breaking
168
173
  ```
169
174
 
170
- 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.
171
176
 
172
- **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:
173
178
 
174
179
  ```bash
175
180
  specshield init
@@ -186,7 +191,9 @@ specshield bdct can-i-deploy --version $GITHUB_SHA
186
191
 
187
192
  ---
188
193
 
189
- ## A Real-World Story
194
+ ## Example: how it plays out
195
+
196
+ *An illustrative scenario:*
190
197
 
191
198
  > The `payment-service` team merged a change that renamed `status` to
192
199
  > `paymentStatus`. The `checkout-ui` team wasn't notified.
@@ -220,30 +227,6 @@ specshield bdct can-i-deploy --version $GITHUB_SHA
220
227
 
221
228
  ---
222
229
 
223
- ## Local vs Cloud
224
-
225
- | Feature | Local (Free) | Team | Enterprise |
226
- |---|---|---|---|
227
- | Compare two spec files | ✅ | ✅ | ✅ |
228
- | Breaking change detection | ✅ | ✅ | ✅ |
229
- | JSON / human output | ✅ | ✅ | ✅ |
230
- | Fail CI on breaking change | ✅ | ✅ | ✅ |
231
- | **`bdct capture from-har`** | ✅ | ✅ | ✅ |
232
- | **`bdct verify-provider`** | ✅ | ✅ | ✅ |
233
- | `specshield history` — compare timeline | ❌ | ✅ | ✅ |
234
- | `specshield share` — public report URLs | ❌ | ✅ | ✅ |
235
- | Hosted dashboard | ❌ | ✅ | ✅ |
236
- | GitHub App PR checks | ❌ | ✅ | ✅ |
237
- | BDCT consumer registry + can-i-deploy gate | ❌ | ✅ | ✅ |
238
- | BDCT compatibility matrix | ❌ | ✅ | ✅ |
239
- | Team workspace + audit log + RBAC | ❌ | ✅ | ✅ |
240
- | Slack notifications | ❌ | ✅ | ✅ |
241
- | SAML SSO, SCIM, on-prem | ❌ | ❌ | ✅ |
242
-
243
- > **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.
244
-
245
- ---
246
-
247
230
  # Commands
248
231
 
249
232
  ## Local Compare
@@ -271,7 +254,8 @@ specshield compare base.yaml target.yaml --ignore "DELETE /admin removed" --fail
271
254
 
272
255
  Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
273
256
  heavy comparison off your CI runner and for cross-validating against the
274
- exact engine the dashboard uses. Requires a free account.
257
+ exact engine the dashboard uses. Requires an API key from a free account —
258
+ without one the CLI exits with code `2` (`No API key found`).
275
259
 
276
260
  ```bash
277
261
  specshield compare base.yaml target.yaml --remote
@@ -279,10 +263,9 @@ specshield compare base.yaml target.yaml --remote --fail-on-breaking
279
263
  specshield compare base.yaml target.yaml --remote --json --output result.json
280
264
  ```
281
265
 
282
- > **History note:** with an API key set (run `specshield login`, or pass
283
- > `--api-key` / `SPECSHIELD_API_KEY`), `--remote` saves each comparison to
284
- > your history and the response includes a `historyId` you can hand to
285
- > `specshield share`. Without a key the diff still runs — it just isn't saved.
266
+ > **History note:** set your key with `specshield login`, `--api-key`, or
267
+ > `SPECSHIELD_API_KEY`. Each `--remote` comparison is saved to your history,
268
+ > and the response includes a `historyId` you can hand to `specshield share`.
286
269
 
287
270
  ## Comparison History
288
271
 
@@ -423,13 +406,15 @@ Run it in CI right after your build:
423
406
 
424
407
  ---
425
408
 
426
- # Bi-Directional Contract Testing (BDCT)
409
+ # Contract Compatibility Testing — the `bdct` commands
427
410
 
428
411
  **Compatibility without Pact's broker overhead or DSL.**
429
412
 
413
+ > **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)**
414
+
430
415
  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.
431
416
 
432
- ### How BDCT Works
417
+ ### How it works
433
418
 
434
419
  1. Consumer publishes a contract (OpenAPI subset *or* Pact JSON).
435
420
  2. Provider publishes its full OpenAPI spec.
@@ -580,7 +565,7 @@ specshield bdct list-consumers --org acme-store --consumer checkout-ui
580
565
  specshield bdct list --org acme-store --provider payment-service --env production
581
566
  ```
582
567
 
583
- ### Full BDCT Workflow
568
+ ### Full workflow
584
569
 
585
570
  ```bash
586
571
  # 1. Provider publishes spec on every release
@@ -600,9 +585,9 @@ specshield bdct can-i-deploy \
600
585
  --version v2.1.0 --env production
601
586
  ```
602
587
 
603
- ### BDCT JSON Output
588
+ ### JSON output
604
589
 
605
- All BDCT commands support `--json` for CI parsing:
590
+ All `bdct` commands support `--json` for CI parsing:
606
591
 
607
592
  ```bash
608
593
  specshield bdct can-i-deploy --org acme-store --service payment-service --version v2.1.0 --json
@@ -626,7 +611,7 @@ specshield bdct can-i-deploy --org acme-store --service payment-service --versio
626
611
 
627
612
  # `bdct capture from-har` — turn real traffic into a consumer contract
628
613
 
629
- **This is the feature that makes BDCT actually work for normal teams.**
614
+ **This is the feature that makes contract testing actually work for normal teams.**
630
615
  Pact requires every consumer team to learn a DSL, instrument their tests,
631
616
  and run a broker. SpecShield asks for something they already have: a
632
617
  recording of an HTTP test run, in the universal HAR format that every
@@ -654,7 +639,7 @@ integration" and "we proved the integration."
654
639
  ```
655
640
 
656
641
  Step 1 already happens in your team — you're just saving the file. Step 2
657
- is one CLI command. Step 3 is the BDCT registry you publish to.
642
+ is one CLI command. Step 3 is the contract registry you publish to.
658
643
 
659
644
  ---
660
645
 
@@ -672,118 +657,10 @@ project. You almost never have to write recorder code yourself.
672
657
  | **[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 |
673
658
  | **[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 |
674
659
 
675
- **Recipes follow** — keep reading for the exact commands per tool, then jump
676
- to Step 2 (the capture command, which is identical regardless of recorder).
677
-
678
- ### 1a. Chrome / Firefox / Edge DevTools (zero code — best for frontend)
679
-
680
- 1. Open the page that calls your API in the browser.
681
- 2. Open DevTools (`F12` / `Cmd+Opt+I`) → **Network** tab.
682
- 3. Click the 🚫 button to clear, then reload the page and click through the
683
- flows you want to record.
684
- 4. Right-click anywhere in the request list → **Save all as HAR with
685
- content** → save as `traffic.har`.
686
-
687
- That's the entire recording. The file is byte-compatible with everything
688
- SpecShield does.
689
-
690
- > **Safari note:** Safari's "Export HAR" is under the Develop menu →
691
- > *Export…* in the Network tab; it produces the same format.
692
-
693
- ### 1b. Playwright (best for teams with UI tests)
694
-
695
- Add one option to your `playwright.config.js`:
696
-
697
- ```js
698
- // playwright.config.js
699
- const path = require('path');
700
- module.exports = {
701
- testDir: './tests',
702
- use: {
703
- baseURL: 'https://staging.acme.com',
704
- recordHar: { path: path.resolve(__dirname, 'traffic.har'), mode: 'full', content: 'embed' },
705
- },
706
- };
707
- ```
708
-
709
- Run your tests as usual:
710
-
711
- ```bash
712
- npx playwright test
713
- # → writes traffic.har on context close
714
- ```
715
-
716
- The HAR will contain every HTTP call the browser made during the test —
717
- HTML, JS, images, and the API JSON. The `--onlyJson` default in Step 2
718
- filters out the noise automatically.
719
-
720
- > Need the HAR file flushed **per test**? Create the context explicitly in
721
- > your test and call `await context.close()` at the end. A runnable
722
- > copy-paste starter lives in [`examples/playwright-har/`](examples/playwright-har/)
723
- > of this repo — clone, `npm install`, `npx playwright install chromium`,
724
- > `npm test` produces `traffic.har` against the public JSONPlaceholder
725
- > sandbox so you can verify the toolchain works before pointing it at your
726
- > own provider.
727
-
728
- ### 1c. Cypress
729
-
730
- ```bash
731
- npm i -D @neuralegion/cypress-har-generator
732
- ```
733
-
734
- ```js
735
- // cypress.config.js
736
- const { install } = require('@neuralegion/cypress-har-generator');
737
- module.exports = { e2e: { setupNodeEvents(on, config) { install(on); return config; } } };
738
-
739
- // cypress/support/e2e.js
740
- beforeEach(() => cy.recordHar());
741
- afterEach(() => cy.saveHar({ outDir: './har-out' }));
742
- ```
743
-
744
- Run `npx cypress run` and the HAR for each spec lands in `har-out/`.
745
-
746
- ### 1d. mitmproxy (best for backend service-to-service)
747
-
748
- When the consumer is a backend service (no browser), point it through
749
- mitmproxy in your integration-test env. No consumer code change.
750
-
751
- ```bash
752
- # Install once
753
- brew install mitmproxy # macOS — also available via pip and apt
754
-
755
- # Start the proxy and tell it to dump HAR
756
- mitmdump --set hardump=traffic.har --listen-port 8080
757
-
758
- # In another terminal: run your tests with HTTPS_PROXY pointing at it
759
- HTTPS_PROXY=http://localhost:8080 HTTP_PROXY=http://localhost:8080 \
760
- ./run-integration-tests.sh
761
-
762
- # Ctrl-C mitmdump when done — traffic.har is on disk
763
- ```
764
-
765
- The `hardump` add-on is built into mitmproxy ≥ 9.0. For TLS hosts you'll
766
- need to trust mitmproxy's CA in your test JVM/runtime (see the
767
- [mitmproxy CA docs](https://docs.mitmproxy.org/stable/concepts-certificates/));
768
- in many test environments it's a single env var
769
- (`NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, or a
770
- JVM `cacerts` import).
771
-
772
- ### 1e. Postman / Insomnia / Bruno
773
-
774
- Run the request (or a whole collection runner). Right-click the response
775
- → **Save Response as HAR**. Repeat for each request you want included,
776
- then either keep them as separate `.har` files (pass `--in` once per file
777
- via a loop in CI) or merge them with any HAR-merge tool.
778
-
779
- ### 1f. k6 load test (bonus — recording while load-testing)
780
-
781
- ```bash
782
- k6 run --out har=traffic.har script.js
783
- ```
784
-
785
- k6 emits a HAR alongside its load metrics. Same file works with
786
- `bdct capture from-har`.
660
+ **Step-by-step recipes for each recorder** (DevTools, Playwright, Cypress,
661
+ mitmproxy, Postman, k6) are in
662
+ [`docs/har-recipes.md`](https://github.com/specshield-io/specshield-cli/blob/main/docs/har-recipes.md).
663
+ The Step 2 command is identical whichever recorder you use.
787
664
 
788
665
  ---
789
666
 
@@ -865,7 +742,7 @@ specshield bdct can-i-deploy \
865
742
  # exit 0 = safe; exit 1 = a verification says NO and the deploy is blocked
866
743
  ```
867
744
 
868
- Full BDCT command reference is in the [Bi-Directional Contract Testing](#bi-directional-contract-testing-bdct)
745
+ Full command reference is in the [Contract Compatibility Testing](#contract-compatibility-testing--the-bdct-commands)
869
746
  section above.
870
747
 
871
748
  ---
@@ -967,26 +844,11 @@ syntax changes.
967
844
 
968
845
  ---
969
846
 
970
- ## Why this is the most valuable piece of the CLI
971
-
972
- Every other contract-testing product on the market asks the consumer team
973
- to **change their code** — adopt a DSL, instrument their tests, run a
974
- broker. That tax is why most teams that "should" be doing contract testing
975
- aren't.
976
-
977
- `bdct capture from-har` removes the tax. Your team's existing test run is
978
- already the contract; the CLI just converts the format. The HAR-capture →
979
- publish → can-i-deploy loop is what turns "we have OpenAPI specs in a
980
- folder" into "no provider PR merges if it would break a deployed consumer"
981
- — with measurable enforcement, in one CI step, and no per-language SDK.
982
-
983
- ---
984
-
985
847
  # `bdct verify-provider` — does your live provider actually match its spec?
986
848
 
987
849
  **Active spec-vs-production conformance — Dredd-style, in CI.**
988
850
 
989
- 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.
851
+ 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.
990
852
 
991
853
  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.
992
854
 
@@ -1101,7 +963,7 @@ jobs:
1101
963
  ### On Push — Publish provider spec + gate the deploy
1102
964
 
1103
965
  ```yaml
1104
- name: BDCT Publish & Deploy Gate
966
+ name: Publish Provider & Deploy Gate
1105
967
  on:
1106
968
  push:
1107
969
  branches: [main]
@@ -1166,7 +1028,7 @@ jobs:
1166
1028
  | | **SpecShield** | **Pact / PactFlow** (SmartBear) | **oasdiff** | **Specmatic** / **Microcks** (OSS) |
1167
1029
  |---|---|---|---|---|
1168
1030
  | OpenAPI-native | ✅ | partial (Pact DSL) | ✅ | ✅ |
1169
- | No broker required | ✅ | ❌ (Pact Broker) | ✅ | ✅ |
1031
+ | No broker to run or host | ✅ | ❌ (Pact Broker or paid PactFlow) | ✅ | ✅ |
1170
1032
  | Bi-directional contract testing | ✅ | ✅ (Pactflow paid) | ❌ | partial |
1171
1033
  | Breaking-change detection | ✅ | ❌ | ✅ | ❌ |
1172
1034
  | `can-i-deploy` gating | ✅ | ✅ (broker) | ❌ | ❌ |
@@ -1187,10 +1049,13 @@ jobs:
1187
1049
  | Plan | Price | What's included |
1188
1050
  |---|---|---|
1189
1051
  | **Free** | $0 forever | Local compare · `bdct capture from-har` · `bdct verify-provider` · public web diff · 7-day compare history · 1 GitHub App PR check |
1190
- | **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 |
1191
- | **Enterprise** | Talk to us | Everything in Team + SAML SSO · SCIM · on-prem / private-cloud · advanced RBAC + audit-log export · dedicated onboarding + SLA |
1052
+ | **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 |
1053
+ | **Enterprise** | Custom · unlimited users | Everything in Team + SSO and on-prem / private-cloud (on request) · advanced RBAC + audit-log export · dedicated onboarding + SLA |
1192
1054
 
1193
- No credit card for the free plan. **[Get started free →](https://specshield.io)** · For Enterprise: [sales@specshield.io](mailto:sales@specshield.io).
1055
+ Prices exclude VAT/GST, added at checkout where applicable. No credit card for the free plan.
1056
+
1057
+ > **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.
1058
+ **[Get started free →](https://specshield.io)** · For Enterprise: [sales@specshield.io](mailto:sales@specshield.io).
1194
1059
 
1195
1060
  ---
1196
1061
 
@@ -1202,7 +1067,7 @@ Run once at the root of your project. The wizard:
1202
1067
  2. Detects your service name (`package.json`, `pyproject.toml`, `pom.xml`, `go.mod`, `Cargo.toml`, or directory name).
1203
1068
  3. Detects your git branch and suggests `production` for `main`/`master`, `staging` otherwise.
1204
1069
  4. Asks whether this project is a provider, a consumer, or both.
1205
- 5. Asks for your org key (autocompletes from your account if signed in).
1070
+ 5. Asks for your org key — copy it from the dashboard at [specshield.io/account/team](https://specshield.io/account/team).
1206
1071
  6. Validates / stores your API key.
1207
1072
  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).
1208
1073
 
@@ -1274,7 +1139,7 @@ specshield init --no-interactive \
1274
1139
  | `--consumer-provider <name>` | The provider this consumer talks to. |
1275
1140
  | `--contract <path>` | Path to the consumer contract (OpenAPI or Pact JSON). |
1276
1141
  | `--format <fmt>` | Consumer contract format: `OPENAPI` (default) or `PACT`. |
1277
- | `--env <environment>` | Default environment for BDCT operations. |
1142
+ | `--env <environment>` | Default environment for `bdct` operations. |
1278
1143
  | `--write-workflow` | Also write a starter GitHub Actions workflow. |
1279
1144
 
1280
1145
  > **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.
@@ -1342,7 +1207,7 @@ remote:
1342
1207
  url: https://specshield.io/compare
1343
1208
  timeout: 10000
1344
1209
 
1345
- # BDCT defaults (used by every `specshield bdct …` subcommand).
1210
+ # `bdct` defaults (used by every `specshield bdct …` subcommand).
1346
1211
  bdct:
1347
1212
  org: acme-pay
1348
1213
  environment: staging
@@ -1366,7 +1231,7 @@ github:
1366
1231
  commentOnPr: true
1367
1232
  ```
1368
1233
 
1369
- With this file, BDCT commands collapse to `--version`:
1234
+ With this file, `bdct` commands collapse to `--version`:
1370
1235
 
1371
1236
  ```bash
1372
1237
  specshield bdct publish-provider --version $GITHUB_SHA
@@ -1390,9 +1255,10 @@ specshield compare <base> <target> [options]
1390
1255
  | `--json` | Machine-readable JSON output |
1391
1256
  | `--output <file>` | Save result to file |
1392
1257
  | `--ignore <change>` | Ignore a specific change (repeatable) |
1393
- | `--severity <level>` | `info` / `warning` / `error` |
1258
+ | `--severity <level>` | Minimum severity shown: `info` / `warning` / `error` (default `info`) |
1394
1259
  | `--config <path>` | Path to `.specshield.yml` |
1395
- | `--timeout <ms>` | Request timeout for remote mode |
1260
+ | `--remote-url <url>` | Override the hosted API base URL |
1261
+ | `--timeout <ms>` | Request timeout for remote mode (default `10000`) |
1396
1262
 
1397
1263
  ```bash
1398
1264
  specshield history [options]
@@ -1413,6 +1279,17 @@ specshield share <reportId | base.yaml target.yaml> [options]
1413
1279
  | `--expires <days>` | Make the link expire after N days (default: never) |
1414
1280
  | `--api-key <key>` | Override stored API key |
1415
1281
 
1282
+ ```bash
1283
+ specshield whoami [options] # show the signed-in account
1284
+ specshield logout # remove the stored API key
1285
+ ```
1286
+
1287
+ | Option (`whoami`) | Description |
1288
+ |---|---|
1289
+ | `--api-token <key>` | Override stored / env API token for this call |
1290
+ | `--server <url>` | Override SpecShield server URL |
1291
+ | `--json` | Machine-readable JSON output |
1292
+
1416
1293
  ```bash
1417
1294
  specshield govern <spec> [options]
1418
1295
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specshield",
3
- "version": "3.4.9",
3
+ "version": "3.4.11",
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",