@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/README.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
 
@@ -225,7 +308,7 @@ Put `--check` after the two schemas, or write `--check=<n>`: an optional value t
225
308
  | --- | --- | --- |
226
309
  | [`scalar auth`](https://scalar.com/tools/cli/commands/auth) | Log in to Scalar and manage your session | `login`, `whoami`, `logout` |
227
310
  | [`scalar access-group`](https://scalar.com/tools/cli/commands/access-group) | Manage access groups, allowed emails and domains for the current team | `list`, `create`, `get`, `update`, `delete`, `domain add`, `domain remove`, `email add`, `email remove` |
228
- | [`scalar document`](https://scalar.com/tools/cli/commands/document) | Work with OpenAPI and AsyncAPI descriptions | `bundle`, `split`, `join`, `format`, `convert`, `markdown`, `mock`, `serve`, `share`, `validate`, `void`, `lint`, `upgrade` |
311
+ | [`scalar document`](https://scalar.com/tools/cli/commands/document) | Work with OpenAPI and AsyncAPI descriptions | `bundle`, `transform`, `split`, `join`, `format`, `convert`, `markdown`, `mock`, `serve`, `share`, `validate`, `void`, `lint`, `upgrade` |
229
312
  | [`scalar project`](https://scalar.com/tools/cli/commands/project) | Manage Scalar Docs projects | `list`, `get`, `init`, `check-config`, `create`, `preview`, `publish`, `rollback`, `deployments list`, `deployments get`, `upgrade` |
230
313
  | [`scalar mcp`](https://scalar.com/tools/cli/commands/mcp) | Manage Scalar-hosted MCP servers | `list`, `get`, `create`, `update`, `delete` |
231
314
  | [`scalar registry`](https://scalar.com/tools/cli/commands/registry) | Manage API descriptions in the Scalar Registry | `publish`, `update`, `delete`, `list`, `get` |
@@ -296,24 +379,26 @@ an authentication failure; authentication failures exit nonzero.
296
379
 
297
380
  SDK metadata fields:
298
381
 
299
- | Field | Type |
300
- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
301
- | `uid`, `namespace`, `slug`, `title`, `description`, `currentVersion` | string |
302
- | `isPrivate` | boolean |
303
- | `createdAt`, `updatedAt` | number, Unix seconds |
304
- | `api` | `null` or `{uid: string, trackedVersion: string \| null, namespace: string \| null, slug: string \| null}` |
305
- | `targets` | Array of `{language: string, slug?: string}` |
306
- | `versions` | Array of version objects below |
307
- | `latestBuild` | Latest build by creation time, or `null` when no build exists |
308
-
309
- Each version has `version: string`, `apiVersion: string`, `status: string`,
310
- `languages: string[]`, `createdAt: number | null`,
311
- `publishedAt: number | null`, and `targets`, an array of
312
- `{language: string, activeBuild: string | null, builtAt: number | null}`.
382
+ | Field | Type |
383
+ | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
384
+ | `uid`, `namespace`, `slug`, `title`, `description`, `currentVersion` | string |
385
+ | `isPrivate` | boolean |
386
+ | `createdAt`, `updatedAt` | number, Unix seconds |
387
+ | `api` | `null` or `{uid: string, namespace: string \| null, slug: string \| null}` |
388
+ | `current` | Object mapping each language with a current build to the version label a request without one serves |
389
+ | `targets` | Array of `{language: string, slug?: string}` |
390
+ | `versions` | Array of version objects below |
391
+ | `latestBuild` | Latest build by creation time, or `null` when no build exists |
392
+
393
+ Versions are listed highest label first. Each version has `version: string`,
394
+ `createdAt: number`, `languages: string[]` (the declared languages it serves a
395
+ build for), and `targets`, an array of
396
+ `{language: string, activeBuild: string, builtAt: number | null}`.
313
397
  Each latest build has `uid: string`, `version: string`, `createdAt: number`,
314
398
  `api: {uid: string, namespace: string, slug: string, version: string}`, and
315
399
  `targets`, an array of
316
- `{language: string, slug?: string, buildStatus: string, gitStatus: string | null}`.
400
+ `{language: string, slug?: string, buildStatus: string, failedStage: string | null, gitStatus: string | null}`.
401
+ `currentVersion` is `current` as one label, the highest when languages differ.
317
402
  All timestamps are Unix seconds. Optional target slugs are omitted when absent;
318
403
  nullable fields are emitted as `null`. Source API coordinates are `null` when
319
404
  the linked API no longer exists. SDK JSON fails if required build or source
@@ -332,9 +417,9 @@ authentication bindings, and build log messages.
332
417
  | `sdk create` | `{uid}` |
333
418
  | `sdk build` | `{uid, namespace, slug, version, status: "started"}` |
334
419
 
335
- All identifiers, coordinates, versions and status values are strings, except
336
- SDK build `version`, which can be `null` if the server does not return its
337
- resolved version. `deleted` is a boolean. Fields shown in each success object
420
+ All identifiers, coordinates, versions and status values are strings. SDK
421
+ build `version` is the API document version the build builds. `deleted` is a
422
+ boolean. Fields shown in each success object
338
423
  are always present. A build receipt means the server accepted the build request,
339
424
  not that generation finished; no build ID is returned by that endpoint.
340
425
  SDK create returns the new SDK UID without an additional metadata request.
@@ -376,7 +461,18 @@ is preserved.
376
461
  Project init and upgrade return absolute paths. `files` lists the files written.
377
462
  Initialization's `availabilityChecked: false` means no authenticated subdomain
378
463
  availability check was performed, not that the subdomain was reserved.
379
- Initialization still requires `--force` to overwrite an existing configuration.
464
+ Initialization checks the configuration, `docs-quickstart.md`, and
465
+ `docs-openapi.json` before writing any project file. If any destination exists,
466
+ an interactive session asks once before replacing the listed conflicts. Without
467
+ an interactive terminal, rerun with `--force` to replace all three init files; `--json` and `--no-input` do not authorize replacement. Directories and
468
+ symlinks are rejected even with `--force`.
469
+
470
+ Files are staged before installation. A handled write failure rolls back this
471
+ initialization's changes. If restoration fails, the command exits with an error
472
+ and reports where recovery files were retained. It does not guarantee recovery
473
+ after a process crash or power loss. If only staging-directory cleanup fails,
474
+ initialization succeeds with a warning. JSON output includes an optional
475
+ `warnings` array with the retained directory path.
380
476
  An already-current config upgrade returns `changed: false`, `files: []`, and
381
477
  `dropped: []`. A completed upgrade reports settings without a v2 equivalent in
382
478
  `dropped`.
@@ -1,39 +1,37 @@
1
1
  import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
2
  import {
3
3
  normalizeVisibility
4
- } from "./chunk-IDGT5RAQ.js";
4
+ } from "./chunk-RELSIFIL.js";
5
5
  import "./chunk-NAC63XJF.js";
6
- import {
7
- writeJson
8
- } from "./chunk-SNQFFEYH.js";
9
- import {
10
- apiService
11
- } from "./chunk-BMQFEKHA.js";
12
- import "./chunk-ANP5XF26.js";
13
- import "./chunk-7FS7BAUX.js";
14
- import "./chunk-Z6HOHGUJ.js";
15
- import "./chunk-EOTD7HAV.js";
16
- import "./chunk-USVU6AC2.js";
17
- import "./chunk-W7P6VTCG.js";
18
- import "./chunk-5D3T63G4.js";
19
- import "./chunk-42MIV6WF.js";
20
- import "./chunk-TR5U7G7T.js";
21
- import "./chunk-DWJMPHLY.js";
22
- import "./chunk-6BQHLHBE.js";
23
- import "./chunk-BOCMOHQA.js";
24
6
  import {
25
7
  requireInteractive,
26
8
  text
27
9
  } from "./chunk-XUX6JXU5.js";
28
10
  import "./chunk-IRQJDPZE.js";
29
- import "./chunk-2KSOARE4.js";
11
+ import {
12
+ writeJson
13
+ } from "./chunk-SNQFFEYH.js";
14
+ import {
15
+ apiService
16
+ } from "./chunk-U36HEOGO.js";
17
+ import "./chunk-MRZ5A7LB.js";
18
+ import "./chunk-CYIGEQOJ.js";
19
+ import "./chunk-4BMOCIYO.js";
20
+ import "./chunk-F6E7FJEC.js";
21
+ import "./chunk-DVA4NCCY.js";
22
+ import "./chunk-BIQFYZP6.js";
23
+ import "./chunk-KSY2GH53.js";
24
+ import "./chunk-ZMJW5UWU.js";
25
+ import "./chunk-7LUXRNKV.js";
30
26
  import {
31
27
  output
32
28
  } from "./chunk-T5HJUAWB.js";
33
- import "./chunk-4S3DGMMZ.js";
34
- import "./chunk-7PNOYE6B.js";
35
- import "./chunk-Q26DFKTY.js";
36
- import "./chunk-I57ID5K7.js";
29
+ import "./chunk-DUIMDHQQ.js";
30
+ import "./chunk-Y3CXAIAG.js";
31
+ import "./chunk-GXKNYM54.js";
32
+ import "./chunk-RGJPENX7.js";
33
+ import "./chunk-5GZAGHKL.js";
34
+ import "./chunk-JBMHCTZD.js";
37
35
  import "./chunk-3MZYUBJ6.js";
38
36
 
39
37
  // src/domains/registry/update/action.ts
@@ -56,6 +54,7 @@ async function updateAction(namespace, slug, {
56
54
  }
57
55
  let titleValue = title;
58
56
  let descriptionValue = description;
57
+ const clearsDescription = description === "";
59
58
  const shouldPrompt = ![title, description, visibility.data].some(
60
59
  (it) => it !== void 0
61
60
  );
@@ -75,7 +74,7 @@ async function updateAction(namespace, slug, {
75
74
  message: `Enter the new API description summary ${as.grey("(optional)")}`
76
75
  });
77
76
  }
78
- if (!titleValue && !descriptionValue && visibility.data === void 0) {
77
+ if (!titleValue && !descriptionValue && !clearsDescription && visibility.data === void 0) {
79
78
  return output.error().title("Invalid input").message(
80
79
  "Provide --title, --description, --public, or --private to update the API description."
81
80
  ).exit("error");
@@ -83,8 +82,8 @@ async function updateAction(namespace, slug, {
83
82
  const client = await apiService();
84
83
  const logger = json ? void 0 : output.info().line().loader("Updating the API description\u2026");
85
84
  const updateDocument = await client.managedDocs.update(namespace, slug, {
86
- title: titleValue,
87
- description: descriptionValue,
85
+ title: titleValue || void 0,
86
+ description: clearsDescription ? "" : descriptionValue || void 0,
88
87
  ...visibility.data === void 0 ? {} : { isPrivate: visibility.data }
89
88
  });
90
89
  if (updateDocument.error) {
@@ -1,25 +1,24 @@
1
1
  import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- config
4
- } from "./chunk-TR5U7G7T.js";
5
- import "./chunk-DWJMPHLY.js";
6
2
  import {
7
3
  getFileOrUrl
8
- } from "./chunk-RRYUCZYO.js";
4
+ } from "./chunk-WGTZEX4Y.js";
9
5
  import {
10
6
  isAsyncApiContent
11
- } from "./chunk-UM3WZUGF.js";
12
- import "./chunk-BY4NGQ5D.js";
13
- import "./chunk-E24BNP6E.js";
7
+ } from "./chunk-CWCRBWA6.js";
8
+ import "./chunk-A2MPF6GE.js";
9
+ import "./chunk-FDW4LC45.js";
14
10
  import "./chunk-4ORL4MST.js";
15
- import "./chunk-2KSOARE4.js";
11
+ import "./chunk-KSY2GH53.js";
12
+ import {
13
+ config
14
+ } from "./chunk-7LUXRNKV.js";
16
15
  import {
17
16
  output
18
17
  } from "./chunk-T5HJUAWB.js";
19
- import "./chunk-4S3DGMMZ.js";
20
- import "./chunk-7PNOYE6B.js";
21
- import "./chunk-Q26DFKTY.js";
22
- import "./chunk-I57ID5K7.js";
18
+ import "./chunk-DUIMDHQQ.js";
19
+ import "./chunk-Y3CXAIAG.js";
20
+ import "./chunk-5GZAGHKL.js";
21
+ import "./chunk-JBMHCTZD.js";
23
22
  import "./chunk-3MZYUBJ6.js";
24
23
 
25
24
  // src/domains/document/share/action.ts
@@ -1,36 +1,34 @@
1
1
  import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- writeJson
4
- } from "./chunk-SNQFFEYH.js";
5
- import {
6
- apiService
7
- } from "./chunk-BMQFEKHA.js";
8
- import "./chunk-ANP5XF26.js";
9
- import "./chunk-7FS7BAUX.js";
10
- import "./chunk-Z6HOHGUJ.js";
11
- import "./chunk-EOTD7HAV.js";
12
- import "./chunk-USVU6AC2.js";
13
- import "./chunk-W7P6VTCG.js";
14
- import "./chunk-5D3T63G4.js";
15
- import "./chunk-42MIV6WF.js";
16
- import "./chunk-TR5U7G7T.js";
17
- import "./chunk-DWJMPHLY.js";
18
- import "./chunk-6BQHLHBE.js";
19
- import "./chunk-BOCMOHQA.js";
20
2
  import {
21
3
  canPrompt,
22
4
  requireInteractive,
23
5
  text
24
6
  } from "./chunk-XUX6JXU5.js";
25
7
  import "./chunk-IRQJDPZE.js";
26
- import "./chunk-2KSOARE4.js";
8
+ import {
9
+ writeJson
10
+ } from "./chunk-SNQFFEYH.js";
11
+ import {
12
+ apiService
13
+ } from "./chunk-U36HEOGO.js";
14
+ import "./chunk-MRZ5A7LB.js";
15
+ import "./chunk-CYIGEQOJ.js";
16
+ import "./chunk-4BMOCIYO.js";
17
+ import "./chunk-F6E7FJEC.js";
18
+ import "./chunk-DVA4NCCY.js";
19
+ import "./chunk-BIQFYZP6.js";
20
+ import "./chunk-KSY2GH53.js";
21
+ import "./chunk-ZMJW5UWU.js";
22
+ import "./chunk-7LUXRNKV.js";
27
23
  import {
28
24
  output
29
25
  } from "./chunk-T5HJUAWB.js";
30
- import "./chunk-4S3DGMMZ.js";
31
- import "./chunk-7PNOYE6B.js";
32
- import "./chunk-Q26DFKTY.js";
33
- import "./chunk-I57ID5K7.js";
26
+ import "./chunk-DUIMDHQQ.js";
27
+ import "./chunk-Y3CXAIAG.js";
28
+ import "./chunk-GXKNYM54.js";
29
+ import "./chunk-RGJPENX7.js";
30
+ import "./chunk-5GZAGHKL.js";
31
+ import "./chunk-JBMHCTZD.js";
34
32
  import "./chunk-3MZYUBJ6.js";
35
33
 
36
34
  // src/domains/project/create/action.ts
@@ -1,58 +1,59 @@
1
1
  import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
+ import {
3
+ defaultWaitSeconds,
4
+ finishPublish,
5
+ timeoutSchema
6
+ } from "./chunk-5EO2CVAR.js";
7
+ import "./chunk-36UI2W7I.js";
2
8
  import {
3
9
  resolveProject
4
10
  } from "./chunk-TSURUX4A.js";
5
11
  import {
6
12
  readAndParseConfig,
7
13
  renderConfigError
8
- } from "./chunk-QMERQSPM.js";
14
+ } from "./chunk-KI2AVDKM.js";
15
+ import "./chunk-S3LY7RKP.js";
9
16
  import {
10
17
  DEFAULT_ASSETS_DIR
11
- } from "./chunk-PIDLENYN.js";
12
- import {
13
- defaultWaitSeconds,
14
- finishPublish,
15
- timeoutSchema
16
- } from "./chunk-G5WWW7VD.js";
17
- import "./chunk-MGGMCT77.js";
18
+ } from "./chunk-M34HMQMV.js";
19
+ import "./chunk-I25ZCHBJ.js";
20
+ import "./chunk-O3I3LTTJ.js";
21
+ import "./chunk-PMDHYIB4.js";
22
+ import "./chunk-O4DJIA6Y.js";
18
23
  import "./chunk-SNQFFEYH.js";
19
- import "./chunk-ERZ3HYB5.js";
20
- import "./chunk-VBHPHAGS.js";
21
- import "./chunk-GOKHFNB2.js";
24
+ import "./chunk-Z7EH7CJC.js";
22
25
  import {
23
26
  apiService
24
- } from "./chunk-BMQFEKHA.js";
25
- import "./chunk-ANP5XF26.js";
26
- import "./chunk-7FS7BAUX.js";
27
- import "./chunk-Z6HOHGUJ.js";
28
- import "./chunk-EOTD7HAV.js";
29
- import "./chunk-USVU6AC2.js";
30
- import "./chunk-W7P6VTCG.js";
31
- import "./chunk-5D3T63G4.js";
27
+ } from "./chunk-U36HEOGO.js";
28
+ import "./chunk-MRZ5A7LB.js";
29
+ import "./chunk-CYIGEQOJ.js";
30
+ import "./chunk-4BMOCIYO.js";
31
+ import "./chunk-F6E7FJEC.js";
32
+ import "./chunk-DVA4NCCY.js";
33
+ import "./chunk-BIQFYZP6.js";
32
34
  import "./chunk-RE5Z56QD.js";
35
+ import "./chunk-4ORL4MST.js";
36
+ import "./chunk-KSY2GH53.js";
33
37
  import "./chunk-VUXPDHTQ.js";
34
38
  import {
35
39
  getAuthData
36
- } from "./chunk-42MIV6WF.js";
37
- import "./chunk-TR5U7G7T.js";
38
- import "./chunk-DWJMPHLY.js";
39
- import "./chunk-6BQHLHBE.js";
40
- import {
41
- ConfigVersion,
42
- isGithubBackedDocsProject
43
- } from "./chunk-BOCMOHQA.js";
44
- import "./chunk-4ORL4MST.js";
45
- import "./chunk-2KSOARE4.js";
40
+ } from "./chunk-ZMJW5UWU.js";
41
+ import "./chunk-7LUXRNKV.js";
46
42
  import {
47
43
  output
48
44
  } from "./chunk-T5HJUAWB.js";
49
- import "./chunk-4S3DGMMZ.js";
50
- import "./chunk-7PNOYE6B.js";
51
- import "./chunk-Q26DFKTY.js";
45
+ import "./chunk-DUIMDHQQ.js";
46
+ import "./chunk-Y3CXAIAG.js";
47
+ import "./chunk-GXKNYM54.js";
48
+ import {
49
+ ConfigVersion,
50
+ isGithubBackedDocsProject
51
+ } from "./chunk-RGJPENX7.js";
52
+ import "./chunk-5GZAGHKL.js";
52
53
  import {
53
54
  slugSchema,
54
55
  zod_default
55
- } from "./chunk-I57ID5K7.js";
56
+ } from "./chunk-JBMHCTZD.js";
56
57
  import "./chunk-3MZYUBJ6.js";
57
58
 
58
59
  // src/domains/project/publish/action.ts