@scalar/cli 2.12.2 → 2.13.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 +221 -2
  2. package/chunks/{action-JXCU2JKC.js → action-27BJMHFD.js} +38 -6
  3. package/chunks/{action-WLPCBFRE.js → action-4EJA6UEB.js} +16 -16
  4. package/chunks/{action-JDXGQSQN.js → action-5MJTAO5X.js} +36 -23
  5. package/chunks/{action-H5XQIZKX.js → action-6FPGU5SY.js} +51 -24
  6. package/chunks/{action-HMPATNVE.js → action-6RQDLMOM.js} +53 -30
  7. package/chunks/{action-Y7EBKCUU.js → action-ASBFLTOA.js} +1 -1
  8. package/chunks/{action-HRRNN33O.js → action-AWHBOHGW.js} +68 -89
  9. package/chunks/{action-UOH5L2JF.js → action-ENN7KFBZ.js} +93 -54
  10. package/chunks/{action-ZNBXKA7T.js → action-ESVI46KE.js} +4 -4
  11. package/chunks/{action-LCTTNNFD.js → action-EVNUUWR5.js} +33 -17
  12. package/chunks/{action-OWWGJ34K.js → action-F6JSCBEU.js} +34 -16
  13. package/chunks/{action-2RIPHL6V.js → action-FZNFBX6U.js} +23 -6
  14. package/chunks/{action-DJ6FLPXH.js → action-GNYNOFDK.js} +15 -5
  15. package/chunks/{action-HOLFCPUY.js → action-JSYHIEYP.js} +12 -12
  16. package/chunks/action-KTY5ICV5.js +55 -0
  17. package/chunks/{action-IIQMZVRJ.js → action-LRR52RXL.js} +10 -8
  18. package/chunks/{action-Z3UXS5KI.js → action-LVYFHK4D.js} +6 -4
  19. package/chunks/{action-XBTIONQD.js → action-NN7QF6MI.js} +9 -6
  20. package/chunks/{action-2GIOY3HU.js → action-OD4GNHM3.js} +48 -28
  21. package/chunks/{action-OY5LI7TW.js → action-OZWRV54F.js} +9 -8
  22. package/chunks/{action-AZNY2B7G.js → action-QZV6IPK4.js} +26 -11
  23. package/chunks/action-S7PMEFCE.js +423 -0
  24. package/chunks/{action-6IL6KE3L.js → action-SZ6SG3RB.js} +16 -16
  25. package/chunks/{action-PRLW546C.js → action-U3MQZ5ZQ.js} +12 -12
  26. package/chunks/action-UAGYB4ZS.js +48 -0
  27. package/chunks/{action-U3R6AXJY.js → action-UVAYACFA.js} +6 -6
  28. package/chunks/{action-7OJTNQRM.js → action-VXEJNBNR.js} +9 -8
  29. package/chunks/{action-KE53K5EJ.js → action-W24B4YT5.js} +14 -14
  30. package/chunks/{action-QA5ATGWB.js → action-WQICTF7K.js} +67 -45
  31. package/chunks/{action-SFRYHYTZ.js → action-WUWWJGRJ.js} +6 -4
  32. package/chunks/{action-II3OJSGP.js → action-Y4YLWZHL.js} +12 -12
  33. package/chunks/{action-2NJJO35T.js → action-YEAOKB6V.js} +13 -11
  34. package/chunks/{action-LGNWFVEG.js → action-YFTRHKOK.js} +63 -48
  35. package/chunks/{action-QEYNGQXG.js → action-YQSSXJAX.js} +10 -7
  36. package/chunks/{action-IYUOT7XX.js → action-ZL2CXRJR.js} +8 -6
  37. package/chunks/{actions-DKQERAKZ.js → actions-GHHWF4Q2.js} +20 -18
  38. package/chunks/{agent-KQKNJZKK.js → agent-XAHNA4MB.js} +3 -3
  39. package/chunks/{asyncapi-MKBEQYBV.js → asyncapi-TICSLZRM.js} +52 -42
  40. package/chunks/{build.action-EGAOPKSX.js → build.action-AURC6QZ6.js} +37 -20
  41. package/chunks/{chunk-ZZTCEMCG.js → chunk-2AK5O3NQ.js} +2 -2
  42. package/chunks/chunk-2I6V7AI3.js +68 -0
  43. package/chunks/chunk-2XWUFFEZ.js +133 -0
  44. package/chunks/{chunk-7GOHWSPA.js → chunk-62OOT7FY.js} +5 -2
  45. package/chunks/{chunk-W2JGSGIQ.js → chunk-7K6I2GUG.js} +15 -9
  46. package/chunks/{chunk-5VZSFLRO.js → chunk-7O5H2SQP.js} +2 -2
  47. package/chunks/{chunk-FJREFWEE.js → chunk-7S34K2P3.js} +1 -1
  48. package/chunks/{chunk-PIWBFJX3.js → chunk-AOZQPCWI.js} +2 -0
  49. package/chunks/{chunk-EBNFCIKS.js → chunk-APX65SRT.js} +2 -1
  50. package/chunks/{chunk-GZA7GEZW.js → chunk-B3XOSR6W.js} +2 -2
  51. package/chunks/{chunk-VJAVNG6U.js → chunk-CSJIKXUD.js} +1 -1
  52. package/chunks/{chunk-MLBEF6MB.js → chunk-DDDYR2HF.js} +1 -1
  53. package/chunks/{chunk-TQL55CUG.js → chunk-EXJUFF6G.js} +1 -1
  54. package/chunks/{chunk-W6FLDNRM.js → chunk-IRA5BW2J.js} +2 -2
  55. package/chunks/chunk-IRQJDPZE.js +34 -0
  56. package/chunks/{chunk-ZK76AK3B.js → chunk-KPLWZIOV.js} +22 -3
  57. package/chunks/chunk-LK2ZIDHH.js +32 -0
  58. package/chunks/{chunk-3DKOVKCV.js → chunk-M2MMGSLK.js} +5 -5
  59. package/chunks/{chunk-FD364GM7.js → chunk-NRHHB3YY.js} +1 -1
  60. package/chunks/{chunk-W3Y5X3X3.js → chunk-OVKTA5CX.js} +12 -5
  61. package/chunks/chunk-PVDORWEM.js +167 -0
  62. package/chunks/chunk-RAJM56L7.js +60 -0
  63. package/chunks/{chunk-UJU2ORWU.js → chunk-RAU5KE6F.js} +1 -1
  64. package/chunks/{chunk-V6LUKXBV.js → chunk-RE5Z56QD.js} +2 -2
  65. package/chunks/chunk-SNQFFEYH.js +11 -0
  66. package/chunks/{chunk-GUF4PKDL.js → chunk-TI4NDKQC.js} +6 -5
  67. package/chunks/{chunk-VRZRTOZF.js → chunk-TKT5UW3G.js} +2 -2
  68. package/chunks/{chunk-A27OERJM.js → chunk-TVPVXL73.js} +7 -7
  69. package/chunks/{chunk-4RF2NKQN.js → chunk-TYNF7ROW.js} +1 -1
  70. package/chunks/{chunk-HDNCXPCZ.js → chunk-VNF2GRZA.js} +2 -2
  71. package/chunks/chunk-WDFZ7WYJ.js +16 -0
  72. package/chunks/{chunk-672Y6REB.js → chunk-WKW5W2ZP.js} +1 -1
  73. package/chunks/chunk-XUX6JXU5.js +58 -0
  74. package/chunks/{chunk-6YOXEMMX.js → chunk-Y2OQOAY7.js} +1 -1
  75. package/chunks/{create.action-UUDVWZ3F.js → create.action-O3HN6GV2.js} +32 -23
  76. package/chunks/{delete.action-XRP3VU5C.js → delete.action-2L2RWLPI.js} +36 -22
  77. package/chunks/{delete.action-EUQ4ESLJ.js → delete.action-KEBI2QCS.js} +38 -22
  78. package/chunks/{get.action-IYA5Q3RI.js → get.action-BUNTDW54.js} +13 -11
  79. package/chunks/{get.action-UHCFOKUQ.js → get.action-WDMTCZZR.js} +14 -14
  80. package/chunks/{list.action-3CCWEEAM.js → list.action-JNSEJVHX.js} +14 -14
  81. package/chunks/{list.action-D3GHA6S5.js → list.action-NSK7OBRH.js} +16 -16
  82. package/chunks/{publish.action-HIVWJ7QE.js → publish.action-ZRZQUL7S.js} +49 -29
  83. package/chunks/{update.action-NSKVEZES.js → update.action-7TA46AE6.js} +36 -22
  84. package/chunks/{update.action-VOZNA7BV.js → update.action-O2R5ODGG.js} +47 -27
  85. package/index.js +226 -149
  86. package/package.json +1 -1
  87. package/skills/scalar-cli/SKILL.md +4 -2
  88. package/template.md +220 -1
  89. package/chunks/action-RNVV27ET.js +0 -165
  90. package/chunks/action-ZHDGAUGG.js +0 -38
  91. package/chunks/chunk-AC62V47N.js +0 -38
  92. package/chunks/chunk-EGOXR5FB.js +0 -15
  93. package/chunks/chunk-JFIXNSPP.js +0 -26
  94. package/chunks/{action-UHXBY3RD.js → action-3P66ZSL3.js} +1 -1
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "engines": {
6
6
  "node": ">=24"
7
7
  },
8
- "version": "2.12.2",
8
+ "version": "2.13.0",
9
9
  "keywords": [
10
10
  "scalar",
11
11
  "openapi",
@@ -5,14 +5,15 @@ 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.12.2).
8
+ Validate, lint, bundle, mock, and preview OpenAPI and AsyncAPI descriptions, and publish them to Scalar (`@scalar/cli` 2.13.0).
9
9
 
10
10
  ## Operating notes
11
11
 
12
12
  - Run `scalar <command>` when the CLI is installed, or `npx @scalar/cli <command>` when it is not.
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`. 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
- - Many commands prompt when a value is left out, such as a slug, a team, or a confirmation before overwriting a file, and a prompt blocks a non-interactive run. 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`.
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
17
  - Results go to stdout. Errors go to stderr, prefixed with `[ERROR]`.
17
18
 
18
19
  ## Exit codes
@@ -61,6 +62,7 @@ Run `scalar context` for the arguments, options, defaults, and choices of each c
61
62
  - `scalar project publish [options]`: Publish a new build of a Scalar project
62
63
  - `scalar project rollback [options]`: Roll the live deployment back to a previously deployed build.
63
64
  - `scalar project deployments list [options]`: List production deployments for a project
65
+ - `scalar project deployments get [options] <build-id>`: Inspect an existing build in the selected team without resubmitting
64
66
  - `scalar project upgrade [options] [config]`: Upgrade a Scalar Docs configuration
65
67
  - `scalar registry publish [options] [file]`: Publish an OpenAPI description to the Scalar Registry
66
68
  - `scalar registry update [options] [namespace] [slug]`: Update API description metadata in the Scalar Registry
package/template.md CHANGED
@@ -38,7 +38,19 @@ scalar document bundle openapi.yaml --output - > openapi.bundled.yaml
38
38
 
39
39
  Pulls every external `$ref` into a single file. `--treeShake` drops components nothing uses. The input can be a URL.
40
40
 
41
- Use `--output -` (or `-o -`) to write YAML to stdout for piping. 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.
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.
42
+
43
+ ### Format files or piped input
44
+
45
+ ```bash
46
+ scalar document format openapi.yaml
47
+ scalar document format openapi.json --output -
48
+ cat openapi.yaml | scalar document format - --output openapi.json
49
+ cat openapi.json | scalar document format -
50
+ cat openapi.json | scalar document format - --output -
51
+ ```
52
+
53
+ Use `-` to read JSON or YAML from stdin and `--output -` to write only document content to stdout in the input’s JSON or YAML format, with diagnostics and timings on stderr. Without `--output`, stdin is formatted to stdout in its original JSON or YAML format. JSON input produces two-space JSON; YAML input produces YAML. URL inputs require an explicit output destination. Named output files use YAML for `.yaml` or `.yml` extensions (case-insensitive), and two-space JSON otherwise. Without `--output`, a local input file is overwritten in place. Use `./-` to refer to a file literally named `-`.
42
54
 
43
55
  ### Preview the API reference
44
56
 
@@ -115,6 +127,22 @@ mkdir -p .claude/skills
115
127
  cp -r "$(npm root -g)/@scalar/cli/skills/scalar-cli" .claude/skills/
116
128
  ```
117
129
 
130
+ ## Noninteractive execution
131
+
132
+ Pass `--no-input` in scripts and agent commands, including when a pseudo-terminal (PTY) is attached:
133
+
134
+ ```sh
135
+ scalar --no-input project create --name "My docs"
136
+ scalar project rollback --slug my-docs --yes --no-input
137
+ scalar document bundle openapi.yaml --output - --no-input
138
+ ```
139
+
140
+ The flag works before or after subcommands. It disables prompts and browser launches. Supply required arguments or options; missing input exits with code 1 and explains what to provide. Optional values retain their defaults, including the generated project slug. Piped data is never read as confirmation.
141
+
142
+ `--no-input` does not imply `--yes` (confirm an action) or `--force` (override a specific protection). Neither flag chooses an unspecified target. Prompt cancellation, Ctrl-C during a prompt, and EOF exit with code 1 and “Operation cancelled.”
143
+
144
+ For `auth login`, supply a personal token using the existing `SCALAR_API_KEY` source or `--token`; without one, noninteractive login fails before starting a browser or callback server. `project preview` still runs the requested preview server but never opens its browser under `--no-input`, even with an opening option. `readme` prints the documentation URL without launching a browser.
145
+
118
146
  ## Use in CI
119
147
 
120
148
  ```yml
@@ -150,3 +178,194 @@ authentication method (browser session or personal token). Use
150
178
  `personal_token`). If the team name cannot be loaded, the team ID remains
151
179
  available and JSON returns `null` for the name. Missing email or role values
152
180
  also return `null`. Credentials are never included.
181
+
182
+ ### Recover a project publish
183
+
184
+ `scalar project publish --slug my-docs` prints the accepted Build ID before waiting up to 600 seconds for deployment. Use `--timeout <seconds>` to change the wait (positive seconds, at most 2147483), or `--no-wait` to return immediately after acceptance. Do not combine `--no-wait` with `--timeout`.
185
+
186
+ Inspect the same production or preview build with the original team selected, without publishing again:
187
+
188
+ ```sh
189
+ scalar project deployments get BUILD_ID
190
+ scalar project deployments get BUILD_ID --wait --timeout 600
191
+ ```
192
+
193
+ A one-shot inspection waits at most 30 seconds for its request unless overridden. It exits zero when the record was read, even if that record reports a failed build. With `--wait`, zero means deployed; a failed build, unavailable status, or expired deadline exits nonzero. `publish --no-wait` exits zero for acceptance, not completed deployment.
194
+
195
+ A status-query error or timeout means the outcome is unknown. Stopping local waiting, including Ctrl-C, does not cancel the remote build. Use the printed Build ID to inspect it later instead of resubmitting.
196
+
197
+ With `publish --json`, successful waiting returns one deployment result. With `--json --no-wait`, acceptance returns `{uid: string, status: "accepted"}`. JSON mode writes no progress to stdout; failures and recovery instructions go to stderr.
198
+
199
+ ### Structured command results
200
+
201
+ Pass `--json` explicitly for machine output. Human output remains the default,
202
+ including when redirected. Success writes one newline-terminated JSON value to
203
+ stdout with exit code 0. Empty lists write `[]`. Failures write human-readable
204
+ diagnostics to stderr, exit nonzero, and do not write a success result to stdout.
205
+ JSON output contains no progress, colors, links, or upgrade notices. In JSON
206
+ mutation mode, missing inputs fail with the required flag instead of prompting,
207
+ even in a terminal.
208
+
209
+ #### List contracts
210
+
211
+ | Command | JSON value |
212
+ | ------------------------------ | -------------------------------------------------------------------------------------------------------- |
213
+ | `team list --json` | Array of `{uid: string, name: string, current: boolean}` |
214
+ | `registry list --json` | Array of `{namespace: string, slug: string, title: string, version: string, isPrivate: boolean}` |
215
+ | `schema list --json` | Array of `{namespace: string, slug: string, title: string, version: string \| null, isPrivate: boolean}` |
216
+ | `sdk list --json` | Array of SDK metadata objects described below |
217
+ | `sdk get --slug <slug> --json` | One SDK metadata object |
218
+
219
+ Schema `version` is the greatest version by semantic-version comparison, or
220
+ `null` when no version exists. Registry `version` is the current version.
221
+ List order is unspecified. These list commands have no pagination flags,
222
+ continuation tokens, or incremental output: each invocation returns a single
223
+ array from the selected team or namespace. Do not interpret an empty array as
224
+ an authentication failure; authentication failures exit nonzero.
225
+
226
+ SDK metadata fields:
227
+
228
+ | Field | Type |
229
+ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
230
+ | `uid`, `namespace`, `slug`, `title`, `description`, `currentVersion` | string |
231
+ | `isPrivate` | boolean |
232
+ | `createdAt`, `updatedAt` | number, Unix seconds |
233
+ | `api` | `null` or `{uid: string, trackedVersion: string \| null, namespace: string \| null, slug: string \| null}` |
234
+ | `targets` | Array of `{language: string, slug?: string}` |
235
+ | `versions` | Array of version objects below |
236
+ | `latestBuild` | Latest build by creation time, or `null` when no build exists |
237
+
238
+ Each version has `version: string`, `apiVersion: string`, `status: string`,
239
+ `languages: string[]`, `createdAt: number | null`,
240
+ `publishedAt: number | null`, and `targets`, an array of
241
+ `{language: string, activeBuild: string | null, builtAt: number | null}`.
242
+ Each latest build has `uid: string`, `version: string`, `createdAt: number`,
243
+ `api: {uid: string, namespace: string, slug: string, version: string}`, and
244
+ `targets`, an array of
245
+ `{language: string, slug?: string, buildStatus: string, gitStatus: string | null}`.
246
+ All timestamps are Unix seconds. Optional target slugs are omitted when absent;
247
+ nullable fields are emitted as `null`. Source API coordinates are `null` when
248
+ the linked API no longer exists. SDK JSON fails if required build or source
249
+ metadata cannot be loaded. It excludes configuration, credentials, repository
250
+ authentication bindings, and build log messages.
251
+
252
+ #### Mutation contracts
253
+
254
+ | Command with `--json` | Success object |
255
+ | ------------------------------------ | ---------------------------------------------------- |
256
+ | `registry publish`, `schema publish` | `{uid, namespace, slug, version}` |
257
+ | `registry update` | `{namespace, slug, status: "updated"}` |
258
+ | `registry delete` | `{namespace, slug, deleted: true}` |
259
+ | `schema update`, `sdk update` | `{uid, namespace, slug, status: "updated"}` |
260
+ | `schema delete`, `sdk delete` | `{uid, namespace, slug, deleted: true}` |
261
+ | `sdk create` | `{uid}` |
262
+ | `sdk build` | `{uid, namespace, slug, version, status: "started"}` |
263
+
264
+ All identifiers, coordinates, versions and status values are strings, except
265
+ SDK build `version`, which can be `null` if the server does not return its
266
+ resolved version. `deleted` is a boolean. Fields shown in each success object
267
+ are always present. A build receipt means the server accepted the build request,
268
+ not that generation finished; no build ID is returned by that endpoint.
269
+ SDK create returns the new SDK UID without an additional metadata request.
270
+ Updates and deletes acknowledge the resolved target; they are not resource
271
+ snapshots. A transport failure can leave a mutation's outcome unknown, so inspect
272
+ the resource before retrying a write.
273
+
274
+ Supply the existing targeting flags and arguments, for example:
275
+
276
+ ```sh
277
+ scalar registry list --namespace acme --json
278
+ scalar registry update acme widgets --title "Widgets API" --json
279
+ scalar schema publish schema.json --namespace acme --slug widget --title Widget --version 1.0.0 --json
280
+ scalar sdk create --namespace acme --api widgets --language typescript --json
281
+ scalar sdk build --namespace acme --slug widgets --json
282
+ ```
283
+
284
+ Team list UIDs can be passed directly to `scalar team set --team <uid>` when
285
+ using browser-session authentication. Personal tokens belong to one team and
286
+ cannot switch teams. Registry/schema list coordinates and SDK list slugs can
287
+ likewise be passed to their mutation commands.
288
+
289
+ #### Team and project results
290
+
291
+ The same explicit JSON mode, stdout/stderr separation, and noninteractive input
292
+ rules apply to the following commands. Existing team and project list/get output
293
+ is preserved.
294
+
295
+ | Command with `--json` | Result |
296
+ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
297
+ | `team set --team <uid>` | `{uid: string, name: string, current: true}` after switching the session |
298
+ | `project create --name <name>` | `{uid: string, slug: string, name: string}`; an omitted slug is generated by the server |
299
+ | `project init --subdomain <name>` | `{configPath: string, subdomain: string, files: string[], availabilityChecked: boolean}` |
300
+ | `project upgrade [config]` | `{configPath: string, changed: boolean, files: string[], dropped: string[]}` |
301
+ | `project publish --slug <slug>` | `{uid: string, status: "deployed", url: string \| null, preview: boolean, hasWarnings: boolean}` |
302
+ | `project rollback --slug <slug> --yes` | `{uid: string, projectUid: string, slug: string, status: "redeployed" \| "already-live"}` |
303
+ | `project deployments list --slug <slug>` | Array of `{uid: string, status: string, current: boolean, createdAt: number, deployedAt: number \| null, commitSha: string \| null}` |
304
+
305
+ Project init and upgrade return absolute paths. `files` lists the files written.
306
+ Initialization's `availabilityChecked: false` means no authenticated subdomain
307
+ availability check was performed, not that the subdomain was reserved.
308
+ Initialization still requires `--force` to overwrite an existing configuration.
309
+ An already-current config upgrade returns `changed: false`, `files: []`, and
310
+ `dropped: []`. A completed upgrade reports settings without a v2 equivalent in
311
+ `dropped`.
312
+
313
+ By default, project publish waits for the deployment to finish in both output modes.
314
+ With `--no-wait`, it returns after acceptance; JSON output is `{uid: string, status: "accepted"}`.
315
+ Its `uid` is the build ID. `url` is null when no public URL can be resolved.
316
+ Warnings about local configuration are sent to stderr; build warnings are
317
+ reported by `hasWarnings`. Failed or cancelled builds exit nonzero without a
318
+ success object. The behavior also applies to `--github` and `--preview`.
319
+
320
+ Rollback requires `--yes` before changing the live deployment. JSON does not
321
+ supply confirmation. `already-live` is a successful no-op and performs no
322
+ redeploy request; `redeployed` acknowledges a successful redeploy request.
323
+ Deployment history includes production builds only, newest creation time first,
324
+ with no pagination flags or continuation tokens. Empty history is `[]`.
325
+ Timestamps are Unix seconds; older records without a deployment timestamp use
326
+ `deployedAt: null`. The full `uid` can be passed to rollback's `--to`:
327
+
328
+ ```sh
329
+ scalar project deployments list --slug docs --json
330
+ scalar project rollback --slug docs --to <build-id> --yes --json
331
+ ```
332
+
333
+ Existing `project list --json` returns an array sorted by slug, while
334
+ `project get <slug> --json` returns one object. Each object contains
335
+ `uid`, `name`, and `slug` (strings), `isPrivate` (boolean), `provider`
336
+ (`github`, `forgejo`, `bitbucket`, or `unlinked`), `repository` (null or
337
+ `{name: string, branch: string, configPath: string}`), and `activeDeployment`
338
+ (null or `{uid: string, domain: string, publishedAt: number}`, with Unix seconds).
339
+ Project listing follows service continuation cursors internally and prints no
340
+ partial list if a cursor or fetch fails. It merges legacy projects, preferring
341
+ unified projects with the same UID or slug.
342
+
343
+ #### Existing access-group contracts
344
+
345
+ Access-group JSON formats remain unchanged:
346
+
347
+ | Command with `--json` | Result |
348
+ | -------------------------------------------- | ----------------------------------------------------------------------- |
349
+ | `access-group list` | Array of group metadata objects; empty `[]` |
350
+ | `access-group get <slug>` | One group metadata object |
351
+ | `access-group create <slug>` | Group metadata plus `createdAt` and `updatedAt` (numbers, Unix seconds) |
352
+ | `access-group update <slug>` | `null` after success |
353
+ | `access-group delete <slug> --yes` | `null` after success |
354
+ | `access-group domain add <slug> <domain>` | `null` after success |
355
+ | `access-group domain remove <slug> <domain>` | `null` after success |
356
+
357
+ Group metadata is `{uid: string, name: string, slug: string,
358
+ allowedDomains: string[], allowedEmails: string[]}`. Ordering is unspecified;
359
+ no pagination flags or continuation tokens are exposed. Deletion requires
360
+ `--yes` in JSON mode even in a terminal. A successful `null` response is an
361
+ acknowledgement, not an empty list or a failed lookup; failures use stderr and a
362
+ nonzero exit status.
363
+
364
+ Long-running project preview, configuration validation, and raw file downloads
365
+ are not mutation-result streams and do not gain `--json` from this feature.
366
+
367
+ ## File and download failures
368
+
369
+ URL input for `document format`, `upgrade`, `markdown`, `mock`, `serve`, `postman`, and `share`, plus Registry and schema publish input, has a 10-second download deadline. `registry get` and `schema get` use the same deadline. It includes reading the response body, but is not a total command runtime limit. Downloads are not automatically retried.
370
+
371
+ File and download failures report the input, a known cause when available, and a recovery step on stderr, with exit code 1. Diagnostic URLs omit credentials, query strings, and fragments. Remote error bodies are not echoed because they may contain credentials; HTTP status remains available. Successful document output is unchanged.
@@ -1,165 +0,0 @@
1
- import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- downloadIsolate
4
- } from "./chunk-VRZRTOZF.js";
5
- import "./chunk-ORCUZITN.js";
6
- import {
7
- readAndParseConfig,
8
- renderConfigError
9
- } from "./chunk-4YQVGOHX.js";
10
- import {
11
- CONFIG_FILE_DEFAULT,
12
- findConfig
13
- } from "./chunk-MQ65WBVF.js";
14
- import {
15
- ISOLATE_DIR
16
- } from "./chunk-UJU2ORWU.js";
17
- import "./chunk-5ENKYZA4.js";
18
- import "./chunk-V6LUKXBV.js";
19
- import "./chunk-VUXPDHTQ.js";
20
- import {
21
- getAuthData
22
- } from "./chunk-MLBEF6MB.js";
23
- import {
24
- config
25
- } from "./chunk-VJAVNG6U.js";
26
- import "./chunk-FD364GM7.js";
27
- import "./chunk-F3TQHNSQ.js";
28
- import {
29
- ConfigVersion
30
- } from "./chunk-VRZSDUZK.js";
31
- import {
32
- requireInteractive
33
- } from "./chunk-EGOXR5FB.js";
34
- import "./chunk-4ORL4MST.js";
35
- import {
36
- output
37
- } from "./chunk-T5HJUAWB.js";
38
- import "./chunk-Q26DFKTY.js";
39
- import "./chunk-I57ID5K7.js";
40
- import "./chunk-3MZYUBJ6.js";
41
-
42
- // src/domains/project/preview/action.ts
43
- import { isCancel, text } from "@clack/prompts";
44
- import as from "ansis";
45
-
46
- // src/domains/project/preview/v2.ts
47
- import { spawn } from "node:child_process";
48
- import path from "node:path";
49
- async function runIsolate(isolateOptions) {
50
- const executable = process.env.SCALAR_CLI_DISTRIBUTION === "portable" ? path.join(
51
- path.dirname(process.execPath),
52
- "runtime",
53
- process.platform === "win32" ? "node.exe" : "node"
54
- ) : process.execPath;
55
- const child = spawn(executable, ["dist/isolate-entry.js"], {
56
- cwd: ISOLATE_DIR,
57
- env: {
58
- ...process.env,
59
- PATH: `${path.dirname(executable)}${path.delimiter}${process.env.PATH ?? ""}`
60
- }
61
- });
62
- child.stdin.write(JSON.stringify(isolateOptions));
63
- child.stdin.end();
64
- child.stdout.pipe(process.stdout);
65
- child.stderr.pipe(process.stderr);
66
- child.on("error", (error) => {
67
- console.error(`Could not start docs preview: ${error.message}`);
68
- process.exitCode = 1;
69
- });
70
- child.on("close", (code, signal) => {
71
- console.log(
72
- `Process exited with code ${code}${signal ? ` (signal ${signal})` : ""}.`
73
- );
74
- process.exitCode = code ?? 1;
75
- });
76
- }
77
- async function getAccessToken() {
78
- try {
79
- const { accessToken } = await getAuthData({ noExit: true });
80
- return accessToken;
81
- } catch {
82
- output.info().message(
83
- "You're not logged in. Private Scalar content will not be fetched."
84
- ).print();
85
- return "";
86
- }
87
- }
88
- async function previewV2Project({
89
- logLevel,
90
- configPath,
91
- port,
92
- config: config2,
93
- host,
94
- openBrowser
95
- }) {
96
- const root = path.resolve(path.dirname(configPath), config2.root ?? "./");
97
- const relativeConfigPath = path.relative(root, configPath);
98
- const accessToken = await getAccessToken();
99
- await downloadIsolate();
100
- output.info().message("Starting preview\u2026").print();
101
- await runIsolate({
102
- configPath: relativeConfigPath,
103
- projectDir: root,
104
- logLevel,
105
- domain: "localhost",
106
- mode: "preview",
107
- previewServerPort: port,
108
- registryBaseUrl: config.projects.registry,
109
- baseUrl: config.services.api,
110
- token: accessToken,
111
- host,
112
- openBrowser
113
- });
114
- }
115
-
116
- // src/domains/project/preview/action.ts
117
- async function previewAction(__configPath, options) {
118
- const _port = Number.parseInt(options.port || "7970", 10);
119
- if (Number.isNaN(_port)) {
120
- return output.error().title("Invalid port").message("Provide a valid port number").exit("error");
121
- }
122
- if (_port < 0 || _port > 65535) {
123
- return output.error().title("Invalid port").message("Port number must be between 0 and 65535").exit("error");
124
- }
125
- let configPath = __configPath || findConfig();
126
- if (!configPath) {
127
- requireInteractive(
128
- "Pass the path to your Scalar configuration file to preview non-interactively."
129
- );
130
- const response = await text({
131
- message: "Where is your configuration file located?",
132
- defaultValue: CONFIG_FILE_DEFAULT,
133
- placeholder: CONFIG_FILE_DEFAULT
134
- });
135
- if (isCancel(response)) return;
136
- configPath = response;
137
- }
138
- const parseConfigResult = readAndParseConfig(configPath);
139
- if (!parseConfigResult.success) {
140
- renderConfigError(parseConfigResult.error);
141
- }
142
- if (parseConfigResult.success) {
143
- output.info().line(
144
- `${as.green("[SUCCESS]")} ${as.green("Configuration is valid:")} ${as.green(parseConfigResult.filePath)}`
145
- ).print();
146
- }
147
- const { config: config2 } = parseConfigResult;
148
- if (config2.version === ConfigVersion.V1) {
149
- return output.error().title("Version 1 previews are no longer supported").message("Run `scalar project upgrade` to upgrade your project.").exit("error");
150
- }
151
- if (config2.version === ConfigVersion.V2) {
152
- await previewV2Project({
153
- logLevel: options.logLevel,
154
- configPath,
155
- config: config2,
156
- port: _port,
157
- host: options.host,
158
- openBrowser: (options.open ?? true) && Boolean(process.stdin.isTTY) && !process.env.CI
159
- });
160
- return;
161
- }
162
- }
163
- export {
164
- previewAction
165
- };
@@ -1,38 +0,0 @@
1
- import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- apiService
4
- } from "./chunk-A27OERJM.js";
5
- import "./chunk-ZZTCEMCG.js";
6
- import "./chunk-ZK76AK3B.js";
7
- import "./chunk-YTTDYTVB.js";
8
- import "./chunk-6YOXEMMX.js";
9
- import "./chunk-5ENKYZA4.js";
10
- import "./chunk-W6FLDNRM.js";
11
- import "./chunk-TQL55CUG.js";
12
- import "./chunk-MLBEF6MB.js";
13
- import "./chunk-VJAVNG6U.js";
14
- import "./chunk-FD364GM7.js";
15
- import "./chunk-F3TQHNSQ.js";
16
- import "./chunk-VRZSDUZK.js";
17
- import "./chunk-4RF2NKQN.js";
18
- import {
19
- output
20
- } from "./chunk-T5HJUAWB.js";
21
- import "./chunk-PIWBFJX3.js";
22
- import "./chunk-Q26DFKTY.js";
23
- import "./chunk-I57ID5K7.js";
24
- import "./chunk-3MZYUBJ6.js";
25
-
26
- // src/domains/registry/delete/action.ts
27
- async function deleteAction(namespace, slug) {
28
- const client = await apiService();
29
- const logger = output.info().line().loader("Deleting the API description\u2026");
30
- const deleteDocument = await client.managedDocs.delete(namespace, slug);
31
- if (deleteDocument.error) {
32
- return output.error().title(deleteDocument.message).exit("error");
33
- }
34
- logger.update("loader", 0, { content: "API description deleted." }).print();
35
- }
36
- export {
37
- deleteAction
38
- };
@@ -1,38 +0,0 @@
1
- import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- registryUrl
4
- } from "./chunk-5VZSFLRO.js";
5
-
6
- // src/domains/registry/helpers/fetch.ts
7
- async function fetchFromRegistry(path, accessToken) {
8
- let response;
9
- try {
10
- response = await fetch(registryUrl(path), {
11
- headers: {
12
- "x-scalar-auth": accessToken
13
- },
14
- // Should always error on redirect
15
- redirect: "error"
16
- });
17
- } catch (error) {
18
- return {
19
- error: true,
20
- message: error instanceof Error && error.message.length > 0 ? error.message : "Registry request failed before a response was received."
21
- };
22
- }
23
- if (!response.ok) {
24
- const message = await response.text();
25
- return {
26
- error: true,
27
- message: message.length ? message : `Registry request failed with status ${response.status}.`
28
- };
29
- }
30
- return {
31
- error: false,
32
- data: await response.text()
33
- };
34
- }
35
-
36
- export {
37
- fetchFromRegistry
38
- };
@@ -1,15 +0,0 @@
1
- import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- output
4
- } from "./chunk-T5HJUAWB.js";
5
-
6
- // src/helpers/interactive.ts
7
- function requireInteractive(message) {
8
- if (!process.stdin.isTTY) {
9
- output.error().title("Missing input").message(message).exit("error");
10
- }
11
- }
12
-
13
- export {
14
- requireInteractive
15
- };
@@ -1,26 +0,0 @@
1
- import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
-
3
- // src/helpers/url-opener.ts
4
- import { exec } from "node:child_process";
5
- var escapeCliArg = (url) => {
6
- return url.replace(/([&])/g, "\\$1");
7
- };
8
- var openBrowser = (url) => {
9
- if (process.env.NODE_ENV === "INTEGRATION") return;
10
- const escapedUrl = escapeCliArg(url);
11
- switch (process.platform) {
12
- case "darwin":
13
- exec(`open ${escapedUrl}`);
14
- break;
15
- case "win32":
16
- exec(`start ${escapedUrl}`);
17
- break;
18
- case "linux":
19
- exec(`xdg-open ${escapedUrl}`);
20
- break;
21
- }
22
- };
23
-
24
- export {
25
- openBrowser
26
- };
@@ -4,11 +4,11 @@ import {
4
4
  renderConfigError
5
5
  } from "./chunk-4YQVGOHX.js";
6
6
  import "./chunk-MQ65WBVF.js";
7
- import "./chunk-5ENKYZA4.js";
8
7
  import "./chunk-VRZSDUZK.js";
9
8
  import {
10
9
  output
11
10
  } from "./chunk-T5HJUAWB.js";
11
+ import "./chunk-5ENKYZA4.js";
12
12
  import "./chunk-I57ID5K7.js";
13
13
  import "./chunk-3MZYUBJ6.js";
14
14