@scalar/cli 2.17.0 → 2.18.0

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 (94) hide show
  1. package/README.md +77 -3
  2. package/chunks/{action-Y4L4OPPH.js → action-2WVJ2WEW.js} +15 -16
  3. package/chunks/{action-UOUS2G2B.js → action-4BDZ2CXP.js} +6 -7
  4. package/chunks/{action-52ZSECW2.js → action-5AXDB5VN.js} +14 -15
  5. package/chunks/{action-7PVWQJ7V.js → action-6I3TJLRO.js} +28 -26
  6. package/chunks/{action-MPBZUWQ2.js → action-6WZN63LT.js} +20 -19
  7. package/chunks/{action-5NYKJDBG.js → action-7GZGVTYI.js} +1067 -766
  8. package/chunks/{action-2Y6UTXAG.js → action-7ZCJAWI2.js} +5 -5
  9. package/chunks/{action-UWVZ6V7B.js → action-A6YOY24G.js} +5 -5
  10. package/chunks/{action-KJJ35X2T.js → action-AGGHY4N2.js} +21 -20
  11. package/chunks/{action-MKZYWAXH.js → action-BVZOA2G5.js} +9 -10
  12. package/chunks/{action-5TQHROY5.js → action-BYDJ4R4F.js} +14 -15
  13. package/chunks/{action-VJDK7ROI.js → action-CBAL5CYB.js} +16 -17
  14. package/chunks/action-COFGCCYS.js +89 -0
  15. package/chunks/action-CYU5Q5LT.js +254 -0
  16. package/chunks/{action-XMANK72Z.js → action-DTQH6CKR.js} +24 -23
  17. package/chunks/{action-AFZE62DU.js → action-ED5WLLIE.js} +6 -7
  18. package/chunks/action-F4CQ4DW3.js +654 -0
  19. package/chunks/{action-TA6VOPQ5.js → action-GVW5PSPT.js} +17 -18
  20. package/chunks/{action-TTDV5NIP.js → action-H5VRLFCY.js} +5 -5
  21. package/chunks/{action-2SZMLOYJ.js → action-IWEAWDT3.js} +9 -10
  22. package/chunks/{action-3EATJRIK.js → action-JN6JVQUV.js} +14 -15
  23. package/chunks/{action-WPUITVPF.js → action-KVM76ZKQ.js} +11 -11
  24. package/chunks/{action-PS4F4QWI.js → action-LLMFEBHH.js} +3 -4
  25. package/chunks/{action-WUMW2GH6.js → action-PEG7AUA6.js} +14 -13
  26. package/chunks/{action-UVWH2KZY.js → action-QC72LLYE.js} +7 -5
  27. package/chunks/{action-P5MGMJG3.js → action-QP6MRSQW.js} +15 -14
  28. package/chunks/{action-W47MFJSP.js → action-R53K22GE.js} +219 -45
  29. package/chunks/{action-RWITXLMW.js → action-SJPWL723.js} +5 -4
  30. package/chunks/{action-SBD4TFRS.js → action-T3R4SDAI.js} +5 -5
  31. package/chunks/{action-GOKWY3AQ.js → action-TT7ZJNST.js} +20 -19
  32. package/chunks/{action-LALZGEVR.js → action-UPVVJE26.js} +14 -15
  33. package/chunks/{action-RM4RZFZV.js → action-V35W4MRK.js} +10 -11
  34. package/chunks/{action-J3C4LAT5.js → action-W4KGRBRV.js} +5 -5
  35. package/chunks/{action-VWQNDXZT.js → action-ZIVYJCC2.js} +14 -15
  36. package/chunks/{action-LI6DZLDZ.js → action-ZU5X2KQX.js} +22 -21
  37. package/chunks/{actions-GWMW7V2B.js → actions-CERT7BL4.js} +16 -16
  38. package/chunks/{actions-4X5RTQCM.js → actions-RCIS37Y6.js} +14 -15
  39. package/chunks/{agent-LB5ZCVUN.js → agent-CT3RRYPJ.js} +7 -7
  40. package/chunks/{asyncapi-J6VAMIMO.js → asyncapi-DVBS23QW.js} +9 -10
  41. package/chunks/{build.action-YP46CGLS.js → build.action-7MKMMV6V.js} +16 -17
  42. package/chunks/{chunk-B3CMXTHQ.js → chunk-36UI2W7I.js} +1 -1
  43. package/chunks/{chunk-4TSZVWGM.js → chunk-4BMOCIYO.js} +19 -4
  44. package/chunks/{chunk-SKXMYIA2.js → chunk-5EO2CVAR.js} +4 -4
  45. package/chunks/{chunk-4YQNT5UH.js → chunk-5GZAGHKL.js} +1 -1
  46. package/chunks/{chunk-3BZ3VY6H.js → chunk-7LUXRNKV.js} +27 -2
  47. package/chunks/{chunk-KDEKIOIP.js → chunk-CWCRBWA6.js} +1 -1
  48. package/chunks/{chunk-YFUHTGGP.js → chunk-CYIGEQOJ.js} +2 -2
  49. package/chunks/{chunk-I4FQOD5L.js → chunk-DVA4NCCY.js} +3 -3
  50. package/chunks/{chunk-63AB5A5B.js → chunk-F6E7FJEC.js} +6 -6
  51. package/chunks/{chunk-2KMYC3ZI.js → chunk-FMPJSW6A.js} +2 -2
  52. package/chunks/{chunk-IZ3UMB7D.js → chunk-GCVB22TG.js} +2 -2
  53. package/chunks/{chunk-36AMOACU.js → chunk-GXKNYM54.js} +3 -3
  54. package/chunks/chunk-I25ZCHBJ.js +22 -0
  55. package/chunks/{chunk-KYCM5SL3.js → chunk-JBMHCTZD.js} +1 -0
  56. package/chunks/{chunk-57EMU765.js → chunk-JEOQ7LSA.js} +1 -1
  57. package/chunks/{chunk-DXEHHE6H.js → chunk-KI2AVDKM.js} +6 -4
  58. package/chunks/{chunk-QDT27U6O.js → chunk-KSY2GH53.js} +2 -2
  59. package/chunks/{chunk-LS6XOFVD.js → chunk-KWQVA66H.js} +11 -23
  60. package/chunks/{chunk-KJT4VYUO.js → chunk-LPWRG2MS.js} +1 -1
  61. package/chunks/{chunk-NKCM2UH5.js → chunk-LVUMNGVA.js} +1 -1
  62. package/chunks/{chunk-H6LOSAC7.js → chunk-M34HMQMV.js} +39 -83
  63. package/chunks/{chunk-XGKFAPON.js → chunk-MRZ5A7LB.js} +4 -4
  64. package/chunks/chunk-O3I3LTTJ.js +24 -0
  65. package/chunks/{chunk-XQPB4OGW.js → chunk-O4DJIA6Y.js} +2 -19
  66. package/chunks/{action-B3IDMFFO.js → chunk-OKLL5422.js} +5 -243
  67. package/chunks/{chunk-RVZZQKVE.js → chunk-PMDHYIB4.js} +4 -22
  68. package/chunks/{chunk-BIYCLKLZ.js → chunk-RELSIFIL.js} +1 -1
  69. package/chunks/{chunk-QLKBXVUV.js → chunk-RGJPENX7.js} +1 -1
  70. package/chunks/{chunk-3KK72EMO.js → chunk-RHAQ4XBA.js} +3 -3
  71. package/chunks/{action-S7DB6MBK.js → chunk-RQ7QBRJT.js} +1 -82
  72. package/chunks/chunk-S3LY7RKP.js +54 -0
  73. package/chunks/{chunk-X2NZINNR.js → chunk-S5OGPH2P.js} +3 -3
  74. package/chunks/{chunk-VNMVAJ6X.js → chunk-U36HEOGO.js} +17 -21
  75. package/chunks/{chunk-CAD672DX.js → chunk-Y3CXAIAG.js} +1 -1
  76. package/chunks/{chunk-HNWIIDGX.js → chunk-Z7EH7CJC.js} +3 -3
  77. package/chunks/{chunk-SVDXXGEO.js → chunk-ZMJW5UWU.js} +3 -3
  78. package/chunks/{chunk-UI5PWDNE.js → chunk-ZQDAPKWX.js} +9 -16
  79. package/chunks/{create.action-PRZKNQHM.js → create.action-VA2ISPIM.js} +16 -17
  80. package/chunks/{delete.action-G7OAQBR5.js → delete.action-AIWMDGXV.js} +16 -17
  81. package/chunks/{delete.action-2BLCOX6Y.js → delete.action-GEN6OD7A.js} +16 -17
  82. package/chunks/{diff.action-KDOJQVJ5.js → diff.action-LBK656RN.js} +15 -14
  83. package/chunks/{get.action-IKO22SCB.js → get.action-5SWRNQ3D.js} +15 -14
  84. package/chunks/{get.action-HSYV5TFY.js → get.action-UPPPGGI4.js} +17 -18
  85. package/chunks/{list.action-KYIFUM3C.js → list.action-YJZBC25S.js} +17 -18
  86. package/chunks/{list.action-IVJS7UFI.js → list.action-YOWWC4I4.js} +19 -20
  87. package/chunks/{publish.action-2QIOUMVY.js → publish.action-QMVDHDJZ.js} +22 -21
  88. package/chunks/{update.action-XZD6T5UR.js → update.action-GFDZIGEP.js} +17 -18
  89. package/chunks/{update.action-7QATFOGP.js → update.action-SNGKPS7A.js} +16 -17
  90. package/index.js +194 -154
  91. package/package.json +11 -11
  92. package/skills/scalar-cli/SKILL.md +3 -2
  93. package/template.md +76 -2
  94. package/chunks/chunk-YTJ67DWS.js +0 -32
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "engines": {
6
6
  "node": ">=24"
7
7
  },
8
- "version": "2.17.0",
8
+ "version": "2.18.0",
9
9
  "keywords": [
10
10
  "scalar",
11
11
  "openapi",
@@ -22,16 +22,16 @@
22
22
  "@clack/prompts": "0.7.0",
23
23
  "@hono/node-server": "2.1.1",
24
24
  "@quobix/vacuum": "0.30.1",
25
- "@scalar/asyncapi-upgrader": "0.1.19",
26
- "@scalar/asyncapi-validator": "0.1.18",
27
- "@scalar/json-magic": "0.19.1",
28
- "@scalar/mock-server": "0.21.0",
29
- "@scalar/openapi-to-markdown": "1.7.4",
30
- "@scalar/openapi-upgrader": "0.4.7",
31
- "@scalar/openapi-validator": "0.1.18",
32
- "@scalar/postman-to-openapi": "0.7.29",
33
- "@scalar/void-server": "2.5.20",
34
- "@scalar/workspace-store": "0.71.1",
25
+ "@scalar/asyncapi-upgrader": "0.1.21",
26
+ "@scalar/asyncapi-validator": "0.1.21",
27
+ "@scalar/json-magic": "0.20.0",
28
+ "@scalar/mock-server": "0.21.3",
29
+ "@scalar/openapi-to-markdown": "1.7.7",
30
+ "@scalar/openapi-upgrader": "0.4.10",
31
+ "@scalar/openapi-validator": "0.1.21",
32
+ "@scalar/postman-to-openapi": "0.7.32",
33
+ "@scalar/void-server": "2.5.23",
34
+ "@scalar/workspace-store": "0.72.0",
35
35
  "@stoplight/spectral-core": "1.22.0",
36
36
  "@stoplight/spectral-parsers": "1.0.5",
37
37
  "@stoplight/spectral-ruleset-bundler": "1.7.0",
@@ -5,7 +5,7 @@ description: "Operate the Scalar CLI (`scalar`, or `npx @scalar/cli`) to validat
5
5
 
6
6
  # Scalar CLI
7
7
 
8
- Validate, lint, bundle, mock, and preview OpenAPI and AsyncAPI descriptions, and publish them to Scalar (`@scalar/cli` 2.17.0).
8
+ Validate, lint, bundle, mock, and preview OpenAPI and AsyncAPI descriptions, and publish them to Scalar (`@scalar/cli` 2.18.0).
9
9
 
10
10
  ## Operating notes
11
11
 
@@ -43,6 +43,7 @@ Run `scalar context` for the arguments, options, defaults, and choices of each c
43
43
  - `scalar access-group email add [options] <slug> <email>`: Add an email address to an access group
44
44
  - `scalar access-group email remove [options] <slug> <email>`: Remove an email address from an access group
45
45
  - `scalar document bundle [options] [file|url]`: Bundle external references into a single API description
46
+ - `scalar document transform [options] <file|url>`: Create public or environment-specific API descriptions
46
47
  - `scalar document split [options] [file|url]`: Split an OpenAPI or AsyncAPI description into referenced JSON files
47
48
  - `scalar document join [options] <files...>`: Join API descriptions of the same format into one description
48
49
  - `scalar document format [options] [file|url]`: Format an OpenAPI or AsyncAPI description
@@ -53,7 +54,7 @@ Run `scalar context` for the arguments, options, defaults, and choices of each c
53
54
  - `scalar document share [options] [file]`: Publish an OpenAPI or AsyncAPI description to a public sandbox
54
55
  - `scalar document validate [options] [file|url]`: Validate an OpenAPI or AsyncAPI description
55
56
  - `scalar document void [options]`: Mirror HTTP requests with a local server
56
- - `scalar document lint [options] [file|url]`: Lint an OpenAPI or AsyncAPI description with Spectral rules
57
+ - `scalar document lint [options] [file|url...]`: Lint OpenAPI or AsyncAPI descriptions with Spectral rules
57
58
  - `scalar document upgrade [options] [file|url]`: Upgrade an API description to OpenAPI 3.1 or the latest supported AsyncAPI version
58
59
  - `scalar project list [options]`: List projects and their slugs for the current team
59
60
  - `scalar project get [options] <slug>`: Show project details for the current team
package/template.md CHANGED
@@ -28,6 +28,46 @@ scalar document lint openapi.yaml --rule .spectral.yaml
28
28
 
29
29
  `validate` checks the document against the OpenAPI or AsyncAPI specification. `lint` applies Spectral rules and fails only on errors. [Lint reports and baselines →](https://scalar.com/tools/cli/ci-and-scripting#lint-reports)
30
30
 
31
+ ### Lint multiple APIs
32
+
33
+ With no inputs, `lint` reads API entries from the existing Scalar configuration file:
34
+
35
+ ```yaml
36
+ # scalar.config.yaml
37
+ scalar: '2.0.0'
38
+ siteConfig: {}
39
+ navigation:
40
+ routes:
41
+ /pets:
42
+ type: openapi
43
+ filepath: ./apis/pets.yaml
44
+ /events:
45
+ type: asyncapi
46
+ filepath: ./apis/events.yaml
47
+ ```
48
+
49
+ ```sh
50
+ scalar document lint
51
+ scalar document lint --format json --output lint-report.json
52
+ scalar document lint --config docs/scalar.config.yaml
53
+ ```
54
+
55
+ No aliases or `--all` flag are needed. The CLI discovers `scalar.config` or `scalar.config.*` in the current directory. If several files match, select one with `--config`. It reads APIs from every version and nested navigation group, including hidden entries, and processes each distinct file path or URL once. Local paths use the config directory and its optional `root`. Legacy config references and public Scalar Registry references are also supported; inaccessible sources are reported as failures.
56
+
57
+ To select inputs directly, pass files or URLs. These bypass config discovery and cannot be combined with `--config`:
58
+
59
+ ```sh
60
+ scalar document lint apis/pets.yaml apis/billing.yaml
61
+ ```
62
+
63
+ Each API uses the default rules for its OpenAPI or AsyncAPI format. `--rule` applies one explicit ruleset to every input; documentation publishing policies in the config do not change this command. Explicit ruleset, report, and ignore-file paths remain relative to the current directory.
64
+
65
+ All report formats support batches. JSON keeps the existing `totals` and `problems` fields, adds an `api` to each problem, and includes an `apis` list with each input's status (`valid`, `invalid`, or `failed`), counts, and execution error if any. Finding locations still point to the physical file, including shared `$ref` targets. A single explicit input retains its existing report shape.
66
+
67
+ The batch continues after an input fails and exits `1` if any API has error-level findings or cannot be linted; warnings alone exit `0`. Execution failures appear as `scalar-lint-execution` errors in combined reports and are always shown. `--max-problems` limits lint findings across the whole batch without changing totals or exit status.
68
+
69
+ One ignore baseline applies to the batch, using the existing Scalar-first, Redocly-fallback discovery in the current directory. `--generate-ignore-file` updates successfully linted APIs and preserves entries for failed or unselected APIs. Findings are matched by physical source, rule, and pointer, so an ignore for a shared reference applies wherever it is used. Reports and baselines cannot overwrite selected inputs, their references, or the selected config.
70
+
31
71
  ### Bundle split files into one
32
72
 
33
73
  ```bash
@@ -49,6 +89,40 @@ When the destination resolves to the input, interactive local use confirms overw
49
89
 
50
90
  Unresolved references fail without changing the output file. Use `--force` (or `-f`) to write an incomplete bundle with warnings and unresolved references retained. For this command, `--force` only permits unresolved references; it does not skip the overwrite confirmation when `--output` is omitted. Tree shaking is skipped when forced reference errors make reachability uncertain. Unreadable or unparseable input, serialization errors, and write errors still fail with `--force`.
51
91
 
92
+ ### Generate public and environment-specific variants
93
+
94
+ ```sh
95
+ scalar document transform api.yaml --config public-production.yaml --output public.yaml
96
+ scalar document transform api.yaml --config private-staging.yaml --output private.json
97
+ scalar document transform api.yaml --config public-production.yaml --output -
98
+ ```
99
+
100
+ Transform accepts JSON/YAML Swagger 2.0, OpenAPI 3.0–3.2, and AsyncAPI 2.x/3.x descriptions supported by Scalar's validators. It preserves the document version. Configuration is a JSON or YAML file; it is never executed as code. Input, configuration, and referenced source files cannot be overwritten, including through symlinks or hardlinks. Output is required. Distinct existing output files must be writable. Regular files are replaced atomically after validation, preserving ownership and permissions; if ownership transfer is denied for a shared writable file, it is updated in place instead. Use `.json`, `.yaml`, or `.yml`; stdout retains the input format, with diagnostics on stderr.
101
+
102
+ Example `public-production.yaml`:
103
+
104
+ ```yaml
105
+ version: 1
106
+ steps:
107
+ - type: remove-internal-operations
108
+ - type: set
109
+ pointer: /servers
110
+ value:
111
+ - url: https://api.example.com
112
+ - type: set
113
+ pointer: /info/title
114
+ value: Public API
115
+ removeUnusedComponents: true
116
+ ```
117
+
118
+ For a private staging variant, omit `remove-internal-operations` and change the server to `https://staging.example.com`. Swagger 2.0 uses set steps for `/host` (`staging.example.com`), `/basePath` (`/v1`), and `/schemes` (`[https]`). AsyncAPI 2.x uses a `/servers` map, such as `{staging: {url: staging.example.com, protocol: amqp}}`; AsyncAPI 3.x uses `{staging: {host: staging.example.com, protocol: amqp}}`. Existing path-, operation-, or channel-level overrides remain unchanged: edit those explicitly, for example `/paths/~1pets/servers` in OpenAPI or `/paths/~1pets/get/schemes` in Swagger 2.0. AsyncAPI 2.x channel server-name lists must still name entries in the replacement map; AsyncAPI 3.x channel server references must still resolve.
119
+
120
+ Steps run in listed order against the bundled document. `set` adds or replaces the value at an exact JSON Pointer; it does not merge objects or append arrays. `remove` deletes an exact target. Escape `/` as `~1` and `~` as `~0` in pointer segments. Parents and array indices must already exist, and removals must match. Root replacement and prototype paths are rejected. Example metadata removal: `{type: remove, pointer: /info/x-internal-notes}`. Examples and other literal data are only edited when explicitly targeted.
121
+
122
+ `remove-internal-operations` removes operations marked `x-internal: true`, including operations under internal paths/channels. It covers OpenAPI paths, webhooks, callbacks and reusable `components/pathItems` (even without component pruning); Swagger paths; AsyncAPI 2.x publish/subscribe; and AsyncAPI 3.x operations. Matching nothing is a successful no-op. Unused reusable content remains unless `removeUnusedComponents: true` is set. That option follows references, security schemes and discriminator mappings, preserves reachable cycles, and removes unused reusable content; AsyncAPI 3.x channels are retained through their operations. This is not a guarantee that all confidential text has been removed: explicitly remove any other private metadata or examples.
123
+
124
+ The sequence is source loading/reference inspection, bundling without pruning, ordered edits on a copy, optional pruning, reference/format validation, then serialization and output. Unresolved source references fail even when a later filter would remove them. Invalid configuration, missing targets, dangling retained references and invalid final descriptions fail without changing the destination. There is no incomplete-output mode. Source formatting and YAML comments are not preserved. Identical source graphs, configuration and CLI versions produce deterministic output; remote URLs must be pinned by the caller for reproducible builds. Dynamic references retain matching dynamic anchors conservatively. Their targets must resolve within the bundled graph; unresolved targets and unsupported `$recursiveRef` semantics fail before writing. This configuration is not OpenAPI Overlay or a plugin API.
125
+
52
126
  ### Format files or piped input
53
127
 
54
128
  ```bash
@@ -204,10 +278,10 @@ jobs:
204
278
  - uses: actions/setup-node@v6
205
279
  with:
206
280
  node-version: 24
207
- - run: npx --yes @scalar/cli document lint openapi.yaml --format github-actions
281
+ - run: npx --yes @scalar/cli document lint --format github-actions
208
282
  ```
209
283
 
210
- `--format github-actions` turns findings into annotations on the pull request. [JSON output, JUnit reports, and lint baselines →](https://scalar.com/tools/cli/ci-and-scripting)
284
+ The CI command lints every API in `scalar.config`. `--format github-actions` turns findings into annotations on the pull request. [JSON output, JUnit reports, and lint baselines →](https://scalar.com/tools/cli/ci-and-scripting)
211
285
 
212
286
  To fail a job when a schema in the repository drifts from the published version, run `schema diff` with `--check`. `--verbose` prints every changed value to the job log, and a distinct exit code such as `--check 2` lets the job tell schema drift apart from an authentication or network error, which exit 1:
213
287
 
@@ -1,32 +0,0 @@
1
- import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- version
4
- } from "./chunk-3BZ3VY6H.js";
5
-
6
- // src/config.ts
7
- import { portNumbers } from "get-port";
8
- var config = {
9
- projects: {
10
- dashboard: process.env.DASHBOARD_URL ?? "https://dashboard.scalar.com",
11
- sandbox: process.env.SANDBOX_URL ?? "https://sandbox.scalar.com",
12
- registry: process.env.REGISTRY_URL ?? "https://registry.scalar.com"
13
- },
14
- mcpUrl: process.env.MCP_URL ?? "https://mcp.scalar.com",
15
- services: {
16
- api: process.env.BASE_URL ?? "https://services.scalar.com"
17
- },
18
- auth: {
19
- /** The auth server the CLI signs in with and trades personal tokens at */
20
- origin: process.env.AUTH_URL ?? "https://auth.scalar.com",
21
- callback: {
22
- preferredPortRange: process.env.PREFERRED_PORT ? Number.parseInt(process.env.PREFERRED_PORT) : portNumbers(4799, 5100)
23
- }
24
- },
25
- cdnUrl: process.env.CDN_URL ?? "https://cdn.scalar.com",
26
- publishTld: process.env.PUBLISH_TLD ?? ((URL.parse(process.env.BASE_URL ?? "", "https://services.scalar.com")?.hostname ?? "services.scalar.com") === "services.scalar.com" ? "apidocumentation.com" : "staging-apidocumentation.com"),
27
- ssgDocsIsolateVersion: process.env.SSG_DOCS_ISOLATE_VERSION ?? version
28
- };
29
-
30
- export {
31
- config
32
- };