@scalar/cli 2.15.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 (112) hide show
  1. package/README.md +121 -25
  2. package/chunks/{action-3W4IC7QL.js → action-2WVJ2WEW.js} +26 -27
  3. package/chunks/{action-HOCCP353.js → action-4BDZ2CXP.js} +12 -13
  4. package/chunks/{action-3QQSKGM3.js → action-5AXDB5VN.js} +21 -23
  5. package/chunks/{action-LD5B5QQ4.js → action-6I3TJLRO.js} +34 -33
  6. package/chunks/{action-T7SD3ETN.js → action-6WZN63LT.js} +299 -75
  7. package/chunks/{action-IUAYC2SC.js → action-7GZGVTYI.js} +1071 -775
  8. package/chunks/{action-2BGAMGXU.js → action-7ZCJAWI2.js} +9 -9
  9. package/chunks/{action-6HFH7DAW.js → action-A6YOY24G.js} +14 -10
  10. package/chunks/{action-IU2AVNOW.js → action-AGGHY4N2.js} +26 -26
  11. package/chunks/{action-B2WWTOF6.js → action-BVZOA2G5.js} +15 -16
  12. package/chunks/{action-2UZWKMSJ.js → action-BYDJ4R4F.js} +18 -19
  13. package/chunks/{action-HDT7EO7W.js → action-CBAL5CYB.js} +19 -21
  14. package/chunks/action-COFGCCYS.js +89 -0
  15. package/chunks/action-CYU5Q5LT.js +254 -0
  16. package/chunks/{action-MJHLG7AE.js → action-DTQH6CKR.js} +33 -33
  17. package/chunks/{action-P2RPH5R2.js → action-ED5WLLIE.js} +11 -12
  18. package/chunks/action-F4CQ4DW3.js +654 -0
  19. package/chunks/{action-SRFBOLDL.js → action-GQDQU2WE.js} +1 -1
  20. package/chunks/{action-PDSSIW2A.js → action-GVW5PSPT.js} +26 -28
  21. package/chunks/{action-WOLNPEUQ.js → action-H5VRLFCY.js} +16 -12
  22. package/chunks/{action-G2WBTXOK.js → action-IWEAWDT3.js} +19 -19
  23. package/chunks/{action-NZJ4Z64U.js → action-JN6JVQUV.js} +16 -18
  24. package/chunks/{action-PNSWHIHC.js → action-KVM76ZKQ.js} +20 -20
  25. package/chunks/{action-JNH4DCZX.js → action-LLMFEBHH.js} +3 -4
  26. package/chunks/{action-QJMRAFOF.js → action-PEG7AUA6.js} +20 -19
  27. package/chunks/{action-2HPMP473.js → action-QC72LLYE.js} +13 -11
  28. package/chunks/{action-ZTLOQZTT.js → action-QP6MRSQW.js} +16 -15
  29. package/chunks/{action-4HXB3YQR.js → action-R53K22GE.js} +230 -52
  30. package/chunks/{action-U2RJ3ZAU.js → action-SJPWL723.js} +6 -5
  31. package/chunks/{action-57SV3ZBM.js → action-T3R4SDAI.js} +9 -9
  32. package/chunks/{action-777R7LOG.js → action-TT7ZJNST.js} +25 -25
  33. package/chunks/{action-TY4BZEMN.js → action-UPVVJE26.js} +18 -19
  34. package/chunks/{action-MBAAYXKK.js → action-V35W4MRK.js} +18 -19
  35. package/chunks/{action-TR2T2UYB.js → action-W4KGRBRV.js} +9 -9
  36. package/chunks/{action-ENDUKGWS.js → action-ZIVYJCC2.js} +16 -18
  37. package/chunks/{action-7LK4RUDP.js → action-ZU5X2KQX.js} +52 -49
  38. package/chunks/{actions-D5OHPBWC.js → actions-CERT7BL4.js} +25 -26
  39. package/chunks/{actions-RI42JY6H.js → actions-RCIS37Y6.js} +22 -24
  40. package/chunks/{agent-NA3QFKJX.js → agent-CT3RRYPJ.js} +7 -7
  41. package/chunks/{asyncapi-YBTWMTW6.js → asyncapi-DVBS23QW.js} +17 -18
  42. package/chunks/{build.action-4YDNDBXC.js → build.action-7MKMMV6V.js} +38 -32
  43. package/chunks/{chunk-MGGMCT77.js → chunk-36UI2W7I.js} +1 -1
  44. package/chunks/chunk-4BMOCIYO.js +536 -0
  45. package/chunks/{chunk-ADQ6B6QI.js → chunk-5DRLDTTU.js} +1 -1
  46. package/chunks/{chunk-G5WWW7VD.js → chunk-5EO2CVAR.js} +6 -6
  47. package/chunks/{chunk-Q26DFKTY.js → chunk-5GZAGHKL.js} +1 -1
  48. package/chunks/{chunk-DWJMPHLY.js → chunk-7LUXRNKV.js} +27 -2
  49. package/chunks/{chunk-BY4NGQ5D.js → chunk-A2MPF6GE.js} +7 -3
  50. package/chunks/{chunk-5D3T63G4.js → chunk-BIQFYZP6.js} +1 -1
  51. package/chunks/chunk-CNJ4TLU7.js +83 -0
  52. package/chunks/{chunk-UM3WZUGF.js → chunk-CWCRBWA6.js} +7 -3
  53. package/chunks/{chunk-Z6HOHGUJ.js → chunk-CYIGEQOJ.js} +2 -2
  54. package/chunks/{chunk-4S3DGMMZ.js → chunk-DUIMDHQQ.js} +1 -1
  55. package/chunks/{chunk-W7P6VTCG.js → chunk-DVA4NCCY.js} +6 -4
  56. package/chunks/chunk-DWWY3LPC.js +85 -0
  57. package/chunks/{chunk-USVU6AC2.js → chunk-F6E7FJEC.js} +18 -12
  58. package/chunks/{chunk-E24BNP6E.js → chunk-FDW4LC45.js} +1 -1
  59. package/chunks/{chunk-TW2UASEW.js → chunk-FMPJSW6A.js} +4 -4
  60. package/chunks/{chunk-IPWJEGPD.js → chunk-GCVB22TG.js} +2 -2
  61. package/chunks/{chunk-6BQHLHBE.js → chunk-GXKNYM54.js} +3 -3
  62. package/chunks/chunk-I25ZCHBJ.js +22 -0
  63. package/chunks/{chunk-I57ID5K7.js → chunk-JBMHCTZD.js} +8 -1
  64. package/chunks/{chunk-KOLEQNLG.js → chunk-JEOQ7LSA.js} +1 -1
  65. package/chunks/{chunk-QMERQSPM.js → chunk-KI2AVDKM.js} +8 -6
  66. package/chunks/{chunk-2KSOARE4.js → chunk-KSY2GH53.js} +3 -3
  67. package/chunks/{chunk-SHRUJFQI.js → chunk-KWQVA66H.js} +105 -18
  68. package/chunks/{chunk-DLYMDGFW.js → chunk-LPWRG2MS.js} +4 -4
  69. package/chunks/{chunk-Y6GKZ2FM.js → chunk-LVUMNGVA.js} +1 -1
  70. package/chunks/{chunk-PIDLENYN.js → chunk-M34HMQMV.js} +42 -83
  71. package/chunks/{chunk-7FS7BAUX.js → chunk-MRZ5A7LB.js} +133 -19
  72. package/chunks/chunk-O3I3LTTJ.js +24 -0
  73. package/chunks/{chunk-VBHPHAGS.js → chunk-O4DJIA6Y.js} +2 -18
  74. package/chunks/chunk-OKLL5422.js +263 -0
  75. package/chunks/{chunk-HIDIW2FN.js → chunk-OQE3WKI3.js} +1 -1
  76. package/chunks/{chunk-ERZ3HYB5.js → chunk-PMDHYIB4.js} +9 -21
  77. package/chunks/{chunk-IDGT5RAQ.js → chunk-RELSIFIL.js} +2 -2
  78. package/chunks/{chunk-BOCMOHQA.js → chunk-RGJPENX7.js} +1 -1
  79. package/chunks/{chunk-7FGJIUDN.js → chunk-RHAQ4XBA.js} +3 -3
  80. package/chunks/chunk-RQ7QBRJT.js +93 -0
  81. package/chunks/chunk-S3LY7RKP.js +54 -0
  82. package/chunks/{chunk-T76K7QNX.js → chunk-S5OGPH2P.js} +3 -3
  83. package/chunks/{chunk-ANP5XF26.js → chunk-U36HEOGO.js} +12625 -1369
  84. package/chunks/{chunk-IPUJEBMI.js → chunk-UWRJCJVG.js} +1 -1
  85. package/chunks/chunk-V7DBDXSJ.js +24 -0
  86. package/chunks/{chunk-RRYUCZYO.js → chunk-WGTZEX4Y.js} +7 -3
  87. package/chunks/{chunk-7PNOYE6B.js → chunk-Y3CXAIAG.js} +30 -3
  88. package/chunks/{chunk-GOKHFNB2.js → chunk-Z7EH7CJC.js} +3 -3
  89. package/chunks/{chunk-42MIV6WF.js → chunk-ZMJW5UWU.js} +6 -5
  90. package/chunks/chunk-ZQDAPKWX.js +111 -0
  91. package/chunks/{create.action-52K3XAYN.js → create.action-VA2ISPIM.js} +27 -29
  92. package/chunks/{delete.action-47LPLTOX.js → delete.action-AIWMDGXV.js} +26 -28
  93. package/chunks/{delete.action-3NMOQPIR.js → delete.action-GEN6OD7A.js} +26 -28
  94. package/chunks/{diff.action-5TLC2EHT.js → diff.action-LBK656RN.js} +32 -27
  95. package/chunks/{get.action-BCMLG7C7.js → get.action-5SWRNQ3D.js} +20 -19
  96. package/chunks/{get.action-TOZ474GO.js → get.action-UPPPGGI4.js} +29 -23
  97. package/chunks/{list.action-6ZWEENT6.js → list.action-YJZBC25S.js} +26 -28
  98. package/chunks/{list.action-CMAA5KTY.js → list.action-YOWWC4I4.js} +54 -25
  99. package/chunks/{publish.action-U3VIU5LZ.js → publish.action-QMVDHDJZ.js} +52 -49
  100. package/chunks/{update.action-UQHZYVTP.js → update.action-GFDZIGEP.js} +27 -29
  101. package/chunks/{update.action-QZOP25ME.js → update.action-SNGKPS7A.js} +26 -28
  102. package/index.js +688 -212
  103. package/package.json +11 -11
  104. package/skills/scalar-cli/SKILL.md +4 -3
  105. package/template.md +120 -24
  106. package/chunks/action-3KP3WVPZ.js +0 -112
  107. package/chunks/action-APBLB3IU.js +0 -235
  108. package/chunks/chunk-BLY2CF4S.js +0 -58
  109. package/chunks/chunk-BMQFEKHA.js +0 -3534
  110. package/chunks/chunk-EOTD7HAV.js +0 -318
  111. package/chunks/chunk-QXOUDBFK.js +0 -92
  112. package/chunks/chunk-TR5U7G7T.js +0 -32
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "engines": {
6
6
  "node": ">=24"
7
7
  },
8
- "version": "2.15.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.18",
26
- "@scalar/asyncapi-validator": "0.1.17",
27
- "@scalar/json-magic": "0.17.0",
28
- "@scalar/mock-server": "0.20.3",
29
- "@scalar/openapi-to-markdown": "1.7.3",
30
- "@scalar/openapi-upgrader": "0.4.6",
31
- "@scalar/openapi-validator": "0.1.17",
32
- "@scalar/postman-to-openapi": "0.7.28",
33
- "@scalar/void-server": "2.5.19",
34
- "@scalar/workspace-store": "0.69.3",
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.15.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
 
@@ -13,7 +13,7 @@ Validate, lint, bundle, mock, and preview OpenAPI and AsyncAPI descriptions, and
13
13
  - Run `scalar context` for this command tree as JSON, or `scalar <command> --help` for a single command.
14
14
  - Log in with a personal token: `scalar auth login --token <token>`, or set `SCALAR_API_KEY` and run `scalar auth login`. An explicit --token overrides SCALAR_API_KEY and must not be empty or whitespace-only. Both store the session on disk for later commands. Without a token, `scalar auth login` opens a browser and waits for a person to log in, so do not run it that way. Check the session with `scalar auth whoami`.
15
15
  - Use --no-input before or after subcommands to disable prompts and browser launches, including under a PTY. Supply required values explicitly; missing inputs fail with exit code 1 and guidance. Piped input is never a confirmation. Cancelled prompts and EOF exit with code 1. The flag does not imply --yes or --force and neither option chooses an unspecified target.
16
- - Many commands prompt when a value is left out, such as a slug, a team, or a confirmation before overwriting a file, and missing values fail when interaction is disabled. Pass every value as an argument or flag: for example `--output` on `document bundle` and `document upgrade`, `--yes` on `project rollback`, and `--force` on `project init`.
16
+ - Many commands prompt when a value is left out, such as a slug, a team, or a confirmation before overwriting a file, and missing values fail when interaction is disabled. Pass every value as an argument or flag: for example `--output` on `document bundle` and `document upgrade`, `--yes` on `project rollback`, and `--force` on `project init` to replace the configuration, docs-quickstart.md, and docs-openapi.json. Project init lists conflicts and stops without --force; --json and --no-input do not grant overwrite permission.
17
17
  - Results go to stdout. Errors go to stderr, prefixed with `[ERROR]`.
18
18
 
19
19
  ## Exit codes
@@ -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,17 +28,100 @@ 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
34
74
  scalar document bundle openapi.yaml --output openapi.bundled.yaml
35
75
  scalar document bundle openapi.yaml --output openapi.bundled.yaml --treeShake
36
76
  scalar document bundle openapi.yaml --output - > openapi.bundled.yaml
77
+ scalar document bundle openapi.yaml --output build/ --ext json
37
78
  ```
38
79
 
39
- Pulls every external `$ref` into a single file. `--treeShake` drops components nothing uses. The input can be a URL.
80
+ Pulls external `$ref` values into a single file, including references in extensions and custom schema keywords. Literal data in examples, defaults, enums, and const values stays unchanged. `--treeShake` drops components nothing uses. The input can be a URL.
81
+
82
+ Bundle output uses `.json`, `.yaml`, or `.yml` filename suffixes to select the format. `--ext json|yaml|yml` overrides the format and replaces recognized output suffixes; other suffixes are retained before appending the selected extension. New extensionless output names receive `.yaml` by default; unrecognized suffixes keep their filename and JSON format unless `--ext` is supplied.
83
+
84
+ Existing files without `--ext` and special destinations (devices and pipes) retain their exact path. Special destinations are written directly. Regular files are replaced atomically, preserving ownership and permissions; both the file and its parent directory must be writable. If ownership transfer is denied for a shared writable file, it is updated in place to preserve ownership; this fallback is not atomic. Hard-link aliases retain the old contents after atomic replacement.
85
+
86
+ Existing output directories and paths ending in a separator receive an input-derived filename. Missing parent directories are created. URL inputs use a decoded, filename-safe pathname basename, or `openapi` when no basename exists. Missing symlink-target parents are not created.
87
+
88
+ When the destination resolves to the input, interactive local use confirms overwriting the original input path in its original format. An incompatible `--ext` requires `--output`. URLs and non-interactive use always require `--output`. Exact `--output -` preserves the root document’s JSON or YAML format, detected from its contents, unless overridden with `--ext`; diagnostics go to stderr.
89
+
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`.
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.
40
123
 
41
- Use `--output -` (or `-o -`) to write to stdout for piping, preserving the root document’s JSON or YAML format. The format is detected from the document contents, including for URLs. Timings, diagnostics, and upgrade notices go to stderr. Without `--output`, local input requires an interactive overwrite confirmation; URL and non-interactive input require an explicit output destination.
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.
42
125
 
43
126
  ### Format files or piped input
44
127
 
@@ -141,7 +224,7 @@ Or with npm:
141
224
  npm install --global @scalar/cli
142
225
  ```
143
226
 
144
- Run `scalar upgrade` to upgrade an npm installation or show portable upgrade instructions, including the installed and latest available versions. Use `scalar upgrade --check` to check without installing, or `scalar upgrade --json` for machine-readable results. Version checks return exit code 1 when the release service cannot be reached or returns invalid data. `scalar --version` remains an offline check of the installed version.
227
+ Run `scalar upgrade` to upgrade a verified global npm installation, including the installed and latest available versions. Project-local, temporary, other-package-manager, and portable installations receive matching instructions without installing anything. The command verifies the version at the target before reporting a completed upgrade. If installation ownership cannot be determined, it explains the limitation and exits with code 1 when an update is available; use the original package manager or installer for that copy. Use `scalar upgrade --check` to check without installing, or `scalar upgrade --json` for machine-readable results. These check modes can report versions successfully even when installation ownership is unknown; their instructions explain the limitation. When already up to date, installation probes are skipped and JSON `instructions` is empty. Package-manager probes run from the home directory with project overrides disabled. The JSON `distribution` field identifies the release channel (`npm` or `portable`), not the package manager. Version checks return exit code 1 when the release service cannot be reached or returns invalid data. `scalar --version` remains an offline check of the installed version.
145
228
 
146
229
  Git ships an unrelated `scalar` executable. If it gets in the way, use npm's `scalar-cli` alias, or run `npm install --global --force @scalar/cli` to replace it. The [installation guide](https://scalar.com/tools/cli/getting-started#installation) covers upgrades and shell completion.
147
230
 
@@ -195,10 +278,10 @@ jobs:
195
278
  - uses: actions/setup-node@v6
196
279
  with:
197
280
  node-version: 24
198
- - run: npx --yes @scalar/cli document lint openapi.yaml --format github-actions
281
+ - run: npx --yes @scalar/cli document lint --format github-actions
199
282
  ```
200
283
 
201
- `--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)
202
285
 
203
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:
204
287
 
@@ -282,24 +365,26 @@ an authentication failure; authentication failures exit nonzero.
282
365
 
283
366
  SDK metadata fields:
284
367
 
285
- | Field | Type |
286
- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
287
- | `uid`, `namespace`, `slug`, `title`, `description`, `currentVersion` | string |
288
- | `isPrivate` | boolean |
289
- | `createdAt`, `updatedAt` | number, Unix seconds |
290
- | `api` | `null` or `{uid: string, trackedVersion: string \| null, namespace: string \| null, slug: string \| null}` |
291
- | `targets` | Array of `{language: string, slug?: string}` |
292
- | `versions` | Array of version objects below |
293
- | `latestBuild` | Latest build by creation time, or `null` when no build exists |
294
-
295
- Each version has `version: string`, `apiVersion: string`, `status: string`,
296
- `languages: string[]`, `createdAt: number | null`,
297
- `publishedAt: number | null`, and `targets`, an array of
298
- `{language: string, activeBuild: string | null, builtAt: number | null}`.
368
+ | Field | Type |
369
+ | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
370
+ | `uid`, `namespace`, `slug`, `title`, `description`, `currentVersion` | string |
371
+ | `isPrivate` | boolean |
372
+ | `createdAt`, `updatedAt` | number, Unix seconds |
373
+ | `api` | `null` or `{uid: string, namespace: string \| null, slug: string \| null}` |
374
+ | `current` | Object mapping each language with a current build to the version label a request without one serves |
375
+ | `targets` | Array of `{language: string, slug?: string}` |
376
+ | `versions` | Array of version objects below |
377
+ | `latestBuild` | Latest build by creation time, or `null` when no build exists |
378
+
379
+ Versions are listed highest label first. Each version has `version: string`,
380
+ `createdAt: number`, `languages: string[]` (the declared languages it serves a
381
+ build for), and `targets`, an array of
382
+ `{language: string, activeBuild: string, builtAt: number | null}`.
299
383
  Each latest build has `uid: string`, `version: string`, `createdAt: number`,
300
384
  `api: {uid: string, namespace: string, slug: string, version: string}`, and
301
385
  `targets`, an array of
302
- `{language: string, slug?: string, buildStatus: string, gitStatus: string | null}`.
386
+ `{language: string, slug?: string, buildStatus: string, failedStage: string | null, gitStatus: string | null}`.
387
+ `currentVersion` is `current` as one label, the highest when languages differ.
303
388
  All timestamps are Unix seconds. Optional target slugs are omitted when absent;
304
389
  nullable fields are emitted as `null`. Source API coordinates are `null` when
305
390
  the linked API no longer exists. SDK JSON fails if required build or source
@@ -318,9 +403,9 @@ authentication bindings, and build log messages.
318
403
  | `sdk create` | `{uid}` |
319
404
  | `sdk build` | `{uid, namespace, slug, version, status: "started"}` |
320
405
 
321
- All identifiers, coordinates, versions and status values are strings, except
322
- SDK build `version`, which can be `null` if the server does not return its
323
- resolved version. `deleted` is a boolean. Fields shown in each success object
406
+ All identifiers, coordinates, versions and status values are strings. SDK
407
+ build `version` is the API document version the build builds. `deleted` is a
408
+ boolean. Fields shown in each success object
324
409
  are always present. A build receipt means the server accepted the build request,
325
410
  not that generation finished; no build ID is returned by that endpoint.
326
411
  SDK create returns the new SDK UID without an additional metadata request.
@@ -362,7 +447,18 @@ is preserved.
362
447
  Project init and upgrade return absolute paths. `files` lists the files written.
363
448
  Initialization's `availabilityChecked: false` means no authenticated subdomain
364
449
  availability check was performed, not that the subdomain was reserved.
365
- Initialization still requires `--force` to overwrite an existing configuration.
450
+ Initialization checks the configuration, `docs-quickstart.md`, and
451
+ `docs-openapi.json` before writing any project file. If any destination exists,
452
+ an interactive session asks once before replacing the listed conflicts. Without
453
+ an interactive terminal, rerun with `--force` to replace all three init files; `--json` and `--no-input` do not authorize replacement. Directories and
454
+ symlinks are rejected even with `--force`.
455
+
456
+ Files are staged before installation. A handled write failure rolls back this
457
+ initialization's changes. If restoration fails, the command exits with an error
458
+ and reports where recovery files were retained. It does not guarantee recovery
459
+ after a process crash or power loss. If only staging-directory cleanup fails,
460
+ initialization succeeds with a warning. JSON output includes an optional
461
+ `warnings` array with the retained directory path.
366
462
  An already-current config upgrade returns `changed: false`, `files: []`, and
367
463
  `dropped: []`. A completed upgrade reports settings without a v2 equivalent in
368
464
  `dropped`.
@@ -1,112 +0,0 @@
1
- import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- measureTime
4
- } from "./chunk-KHDYYVYF.js";
5
- import "./chunk-RRYUCZYO.js";
6
- import "./chunk-UM3WZUGF.js";
7
- import {
8
- DEFAULT_FETCH_CONCURRENCY
9
- } from "./chunk-BLY2CF4S.js";
10
- import "./chunk-DFOZG7ZV.js";
11
- import {
12
- confirm,
13
- requireInteractive
14
- } from "./chunk-XUX6JXU5.js";
15
- import "./chunk-IRQJDPZE.js";
16
- import "./chunk-BY4NGQ5D.js";
17
- import "./chunk-E24BNP6E.js";
18
- import {
19
- isUrl,
20
- isYamlFileName
21
- } from "./chunk-4ORL4MST.js";
22
- import "./chunk-2KSOARE4.js";
23
- import {
24
- output
25
- } from "./chunk-T5HJUAWB.js";
26
- import "./chunk-4S3DGMMZ.js";
27
- import "./chunk-7PNOYE6B.js";
28
- import "./chunk-Q26DFKTY.js";
29
- import "./chunk-I57ID5K7.js";
30
- import "./chunk-3MZYUBJ6.js";
31
-
32
- // src/domains/document/bundle/action.ts
33
- import fs from "node:fs/promises";
34
- import path from "node:path";
35
- import { cwd } from "node:process";
36
- import as from "ansis";
37
- import YAML from "yaml";
38
- import { bundle } from "@scalar/json-magic/bundle";
39
- import { fetchUrls, readFiles } from "@scalar/json-magic/bundle/plugins/node";
40
- import { isJsonObject } from "@scalar/json-magic/helpers/is-json-object";
41
- async function bundleAction(input, {
42
- output: outputFilePath,
43
- treeShake,
44
- urlMap,
45
- fetchLimit
46
- }) {
47
- if (!input) {
48
- return output.error().title("Missing input").message("Provide a file path or URL to bundle.").exit("error");
49
- }
50
- const isUrlInput = isUrl(input);
51
- if (!outputFilePath) {
52
- if (isUrlInput) {
53
- return output.error().message("URL input requires an output file. Use `--output <file>`.").exit("error");
54
- }
55
- requireInteractive(
56
- "Pass --output to bundle a document in non-interactive mode."
57
- );
58
- const shouldContinue = await confirm({
59
- message: `No output file was specified. Overwrite "${input}"?`,
60
- initialValue: false
61
- });
62
- if (shouldContinue !== true) {
63
- return output.error().message("Operation cancelled.").exit("error");
64
- }
65
- }
66
- const outputFileName = outputFilePath ?? input;
67
- const isStdout = outputFilePath === "-";
68
- const resolvedInput = isUrlInput ? input : path.resolve(cwd(), input);
69
- const fileLoader = readFiles();
70
- const urlLoader = fetchUrls({
71
- limit: fetchLimit ?? DEFAULT_FETCH_CONCURRENCY
72
- });
73
- const { result: bundled, executionTimeMs } = await measureTime(async () => {
74
- const root = isStdout ? await (isUrlInput ? urlLoader : fileLoader).exec(resolvedInput) : void 0;
75
- const result2 = await bundle(resolvedInput, {
76
- plugins: [
77
- ...root ? [
78
- {
79
- type: "loader",
80
- validate: (value) => value === resolvedInput,
81
- exec: async () => root
82
- }
83
- ] : [],
84
- fileLoader,
85
- urlLoader
86
- ],
87
- treeShake: !!treeShake,
88
- urlMap: !!urlMap
89
- });
90
- return {
91
- result: result2,
92
- isYaml: root?.ok ? !isJsonObject(root.raw.trimStart()) : isYamlFileName(outputFileName)
93
- };
94
- });
95
- const { result, isYaml } = bundled;
96
- const serialized = isYaml ? YAML.stringify(result) : JSON.stringify(result);
97
- if (isStdout) {
98
- process.stdout.write(serialized);
99
- process.stderr.write(
100
- `API description bundled (${Math.round(executionTimeMs)} ms)
101
- `
102
- );
103
- return;
104
- }
105
- await fs.writeFile(outputFileName, serialized, "utf8");
106
- output.info().message(
107
- `${as.green("API description bundled")} (${as.white(`${as.bold(`${Math.round(executionTimeMs)}`)} ms`)})`
108
- ).line(`Written to ${as.cyan(outputFileName)}`).print();
109
- }
110
- export {
111
- bundleAction
112
- };
@@ -1,235 +0,0 @@
1
- import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- isDocument
4
- } from "./chunk-RRYUCZYO.js";
5
- import {
6
- isAsyncApiDocument
7
- } from "./chunk-UM3WZUGF.js";
8
- import "./chunk-BY4NGQ5D.js";
9
- import "./chunk-E24BNP6E.js";
10
- import {
11
- isUrl
12
- } from "./chunk-4ORL4MST.js";
13
- import "./chunk-2KSOARE4.js";
14
- import {
15
- output
16
- } from "./chunk-T5HJUAWB.js";
17
- import {
18
- err,
19
- ok
20
- } from "./chunk-4S3DGMMZ.js";
21
- import "./chunk-7PNOYE6B.js";
22
- import "./chunk-Q26DFKTY.js";
23
- import "./chunk-I57ID5K7.js";
24
- import "./chunk-3MZYUBJ6.js";
25
-
26
- // src/domains/document/validate/action.ts
27
- import path from "node:path";
28
- import as from "ansis";
29
- import prettyjson from "prettyjson";
30
- import { validate as validateAsyncApi } from "@scalar/asyncapi-validator";
31
- import { bundle } from "@scalar/json-magic/bundle";
32
- import { fetchUrls, readFiles } from "@scalar/json-magic/bundle/plugins/node";
33
- import { validate as validateOpenApi } from "@scalar/openapi-validator";
34
-
35
- // src/domains/document/validate/resolve-for-validation.ts
36
- import { createMagicProxy, getRaw } from "@scalar/json-magic/magic-proxy";
37
- var childContext = (context, key, swagger) => {
38
- if (context === "data") return "data";
39
- if (context === "path-items") return "path-item";
40
- if (context === "callbacks") return "callback";
41
- if (context === "callback") return key.startsWith("x-") ? "data" : "path-item";
42
- if (context === "schemas") return "schema";
43
- if (context === "objects") return "object";
44
- if (context === "responses") return "response";
45
- if (context === "links") return "link";
46
- if (context === "schema") {
47
- if ([
48
- "properties",
49
- "patternProperties",
50
- "dependentSchemas",
51
- "$defs",
52
- "definitions"
53
- ].includes(key))
54
- return "schemas";
55
- if ([
56
- "items",
57
- "additionalProperties",
58
- "unevaluatedProperties",
59
- "unevaluatedItems",
60
- "contains",
61
- "contentSchema",
62
- "propertyNames",
63
- "not",
64
- "if",
65
- "then",
66
- "else",
67
- "allOf",
68
- "anyOf",
69
- "oneOf",
70
- "prefixItems"
71
- ].includes(key))
72
- return "schema";
73
- return "data";
74
- }
75
- if (context === "link" && ["parameters", "requestBody"].includes(key))
76
- return "data";
77
- if (context === "response" && swagger && key === "examples") return "data";
78
- if (["paths", "webhooks", "pathItems"].includes(key)) return "path-items";
79
- if (key === "callbacks") return "callbacks";
80
- if (key === "responses") return "responses";
81
- if (key === "links") return "links";
82
- if (key.startsWith("x-")) return "data";
83
- if (["example", "default", "enum", "const", "value"].includes(key))
84
- return "data";
85
- if (key === "examples") return "objects";
86
- if (["schemas", "definitions", "$defs"].includes(key)) return "schemas";
87
- if (key === "schema") return "schema";
88
- if ([
89
- "content",
90
- "parameters",
91
- "headers",
92
- "requestBodies",
93
- "securitySchemes",
94
- "channels",
95
- "messages",
96
- "operations"
97
- ].includes(key))
98
- return "objects";
99
- return "object";
100
- };
101
- var resolveForValidation = (document) => {
102
- const errors = /* @__PURE__ */ new Set();
103
- const schemaSiblingsApply = typeof document.openapi === "string" && /^3\.[1-9]/.test(document.openapi);
104
- const cache = /* @__PURE__ */ new WeakMap();
105
- const visit = (value, ancestors, context, referenceAncestors = /* @__PURE__ */ new Set()) => {
106
- if (context === "data") return getRaw(value);
107
- if (value === null || typeof value !== "object") {
108
- return value;
109
- }
110
- const raw = getRaw(value);
111
- if (ancestors.has(raw)) {
112
- if (referenceAncestors.has(raw) && "$ref" in value) {
113
- errors.add(`Circular reference has no concrete target: ${value.$ref}`);
114
- }
115
- return {};
116
- }
117
- const cached = cache.get(raw);
118
- if (cached?.has(context)) return cached.get(context);
119
- const remember = (result2) => {
120
- const contexts = cache.get(raw) ?? /* @__PURE__ */ new Map();
121
- contexts.set(context, result2);
122
- cache.set(raw, contexts);
123
- return result2;
124
- };
125
- const next = new Set(ancestors).add(raw);
126
- if (Array.isArray(value)) {
127
- return remember(
128
- value.map(
129
- (entry) => visit(
130
- entry,
131
- next,
132
- context === "objects" ? "object" : context === "schemas" ? "schema" : context
133
- )
134
- )
135
- );
136
- }
137
- const node = value;
138
- const siblings = Object.fromEntries(
139
- Object.entries(node).filter(
140
- ([key]) => (typeof node.$ref !== "string" || context === "path-item" || context === "schema" && schemaSiblingsApply) && key !== "$ref-value" && (key !== "$ref" || typeof node.$ref !== "string")
141
- ).map(([key, entry]) => [
142
- key,
143
- visit(
144
- entry,
145
- next,
146
- childContext(context, key, document.swagger === "2.0")
147
- )
148
- ])
149
- );
150
- if (typeof node.$ref !== "string") {
151
- return remember(siblings);
152
- }
153
- const target = node["$ref-value"];
154
- if (target === void 0) {
155
- errors.add(`Could not resolve reference: ${node.$ref}`);
156
- return remember(siblings);
157
- }
158
- const resolved = visit(
159
- target,
160
- next,
161
- context,
162
- new Set(referenceAncestors).add(raw)
163
- );
164
- if (context === "schema" && schemaSiblingsApply) {
165
- return remember({ allOf: [siblings, resolved] });
166
- }
167
- if (context === "path-item" && resolved !== null && typeof resolved === "object" && !Array.isArray(resolved)) {
168
- return remember({ ...resolved, ...siblings });
169
- }
170
- return remember(resolved);
171
- };
172
- const result = visit(createMagicProxy(document), /* @__PURE__ */ new Set(), "object");
173
- if (errors.size) return err([...errors].join("\n"));
174
- if (!result || typeof result !== "object" || Array.isArray(result)) {
175
- return err("The resolved document must be an object.");
176
- }
177
- return ok(result);
178
- };
179
-
180
- // src/domains/document/validate/action.ts
181
- async function validateAction(inputArgument) {
182
- const startTime = performance.now();
183
- if (!inputArgument) {
184
- return output.error().title("Invalid argument").message("Provide a file path or URL.").exit("error");
185
- }
186
- const document = await bundle(
187
- isUrl(inputArgument) ? inputArgument : path.resolve(inputArgument),
188
- {
189
- plugins: [readFiles(), fetchUrls()],
190
- treeShake: false
191
- }
192
- ).catch((error) => {
193
- return output.error().title("Invalid input").message(error instanceof Error ? error.message : String(error)).exit("error");
194
- });
195
- if (!isDocument(document)) {
196
- return output.error().title("Invalid input").message("Provide a valid JSON or YAML document.").exit("error");
197
- }
198
- const resolved = resolveForValidation(document);
199
- if (!resolved.ok) {
200
- return output.error().title("Invalid reference").message(resolved.error).exit("error");
201
- }
202
- const isAsyncApi = isAsyncApiDocument(document);
203
- const specification = isAsyncApi ? "AsyncAPI" : "OpenAPI";
204
- const initialResult = isAsyncApi ? validateAsyncApi(document) : validateOpenApi(document);
205
- const result = isAsyncApi || !initialResult.valid ? initialResult : validateOpenApi(resolved.data, { checkPathParameters: true });
206
- if (result.valid && result.version) {
207
- const endTime = performance.now();
208
- output.info().line(
209
- as.green(
210
- `Matches the ${specification} specification${as.white(` (${specification} ${as.bold(result.version)})`)}
211
- `
212
- )
213
- ).line(
214
- `${as.green("API description validated")} ${as.grey(
215
- `(${as.white(`${as.bold(`${Math.round(endTime - startTime)}`)} ms`)})
216
- `
217
- )}`
218
- ).print();
219
- } else {
220
- output.error().message(prettyjson.render(result.errors)).message(
221
- as.red(
222
- `File does not match the ${specification} ${result.version ? `${result.version} ` : ""}specification.`
223
- )
224
- ).message(
225
- as.red(
226
- `${as.bold(
227
- `${result.errors?.length ?? 0} error${result.errors?.length === 1 ? "" : "s"}`
228
- )} found.`
229
- )
230
- ).exit("error");
231
- }
232
- }
233
- export {
234
- validateAction
235
- };