@scalar/cli 2.7.1 → 2.10.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.
- package/README.md +475 -80
- package/chunks/action-4GZI2M5B.js +62 -0
- package/chunks/action-4W5GUGEG.js +63 -0
- package/chunks/{action-HJYZCPUN.js → action-5LF4XYHX.js} +10 -7
- package/chunks/{action-SRBN7N3R.js → action-5N3P43MD.js} +17 -12
- package/chunks/{action-RBOLLIGX.js → action-5RL4NWUZ.js} +17 -17
- package/chunks/{action-SNPOOW6S.js → action-657A4K2D.js} +16 -16
- package/chunks/{action-EOAVVL52.js → action-7XOHYWYM.js} +11 -14
- package/chunks/{action-AQRPFQKI.js → action-CABLS46Q.js} +9 -7
- package/chunks/{action-F7A2K74G.js → action-CB55NWAU.js} +9 -13
- package/chunks/{action-5SK5NE7E.js → action-DKDRAIKV.js} +11 -14
- package/chunks/{action-7PEQXDWT.js → action-DTEO4YNX.js} +127 -20
- package/chunks/{action-BAQYJ6UE.js → action-EAUTQ77U.js} +27 -23
- package/chunks/{action-QYGOPSTY.js → action-FBRY5JKU.js} +16 -16
- package/chunks/{action-VOFDW3U2.js → action-GFLRD7LO.js} +6 -5
- package/chunks/{action-LPVITMWA.js → action-GWYYTUTM.js} +4 -3
- package/chunks/{action-4NGK5XMD.js → action-HT42NUUX.js} +29 -24
- package/chunks/action-JEYDBB3P.js +147 -0
- package/chunks/{action-E4YSRFGT.js → action-KDUFU7TZ.js} +11 -13
- package/chunks/{action-BRSSC2SR.js → action-LYCNT3KA.js} +29 -10
- package/chunks/{action-CA4QYPI6.js → action-OJ2NK25F.js} +4 -8
- package/chunks/{action-NVI5DWFP.js → action-PAM2EZ22.js} +4 -8
- package/chunks/action-PPTFYZWD.js +1552 -0
- package/chunks/{action-OX2566BE.js → action-R4PGILN4.js} +30 -26
- package/chunks/{action-CPLH2CQ5.js → action-TOBU74JH.js} +23 -19
- package/chunks/action-U2L5DCFG.js +91 -0
- package/chunks/{action-H6OUJWWM.js → action-UUL6SWV4.js} +11 -14
- package/chunks/{action-T5XMJXPO.js → action-X7BA7PQQ.js} +10 -8
- package/chunks/{action-LVDU6YOI.js → action-XLE37MZL.js} +16 -16
- package/chunks/{action-BOZNBCNZ.js → action-XOADBXSX.js} +16 -12
- package/chunks/{action-SCOXTCPR.js → action-YSVTZVKV.js} +38 -19
- package/chunks/{action-YRX6SN5F.js → action-ZFI77WA5.js} +8 -6
- package/chunks/{action-ATGZOWSH.js → action-ZKA3RR3S.js} +15 -11
- package/chunks/actions-3SAMH7A5.js +182 -0
- package/chunks/{agent-ASPV3R5U.js → agent-2ESZI7NO.js} +7 -5
- package/chunks/{asyncapi-H4FU6GPC.js → asyncapi-4HGVM3PR.js} +14 -10
- package/chunks/{build.action-6V6GXI3X.js → build.action-VBGFGACM.js} +21 -19
- package/chunks/chunk-35Z7VTJT.js +453 -0
- package/chunks/chunk-36LXIJIZ.js +52 -0
- package/chunks/{chunk-BIKOD3SG.js → chunk-43WALAW3.js} +251 -103
- package/chunks/{chunk-C2KAWRIX.js → chunk-5ENKYZA4.js} +1 -1
- package/chunks/{chunk-ZJVYOZFB.js → chunk-5SMP756H.js} +2 -2
- package/chunks/{chunk-5JLVQVKO.js → chunk-6M7TL2G2.js} +146 -148
- package/chunks/chunk-6PSYZO3U.js +24 -0
- package/chunks/{chunk-ISXH6Q7I.js → chunk-ATNTXKMS.js} +45 -274
- package/chunks/{chunk-BDEPNGTO.js → chunk-BIMLCGKS.js} +1 -1
- package/chunks/{chunk-HGOD6THU.js → chunk-CWVYOXXM.js} +2 -19
- package/chunks/chunk-DFOZG7ZV.js +15 -0
- package/chunks/chunk-DHZW7Q7U.js +133 -0
- package/chunks/{chunk-R5LK6VPY.js → chunk-G4HRW2FZ.js} +13 -20
- package/chunks/{chunk-KCCFN4F7.js → chunk-GLWTVLKM.js} +29 -29
- package/chunks/{chunk-5UHLAJQD.js → chunk-GYRQPDTK.js} +24 -10
- package/chunks/chunk-H467HDVV.js +24 -0
- package/chunks/chunk-IPZP3VRA.js +327 -0
- package/chunks/{chunk-LG7IFACX.js → chunk-JXGF5EHC.js} +152 -18
- package/chunks/chunk-K2HIB5BA.js +92 -0
- package/chunks/{chunk-FDC2IESH.js → chunk-KHF2QXBG.js} +1352 -8327
- package/chunks/{chunk-IMG35UXX.js → chunk-KZNRQVMY.js} +1 -1
- package/chunks/{chunk-OJ2EWIJH.js → chunk-MC4EMNOR.js} +5 -1
- package/chunks/{chunk-YILQODZF.js → chunk-MMWSCTDB.js} +7 -4
- package/chunks/{chunk-6XWCMJDB.js → chunk-MNNGUUKJ.js} +12 -11
- package/chunks/chunk-NAC63XJF.js +10 -0
- package/chunks/{chunk-XXSQUBXS.js → chunk-UDBSV3CK.js} +107 -453
- package/chunks/{chunk-IKT5F47M.js → chunk-VVRUSQCY.js} +11 -11
- package/chunks/{chunk-2PPRO2QB.js → chunk-VYFGRLVQ.js} +1 -1
- package/chunks/{chunk-GPNB7ISG.js → chunk-WB6PWTMU.js} +5 -13
- package/chunks/{chunk-4X47MN6Q.js → chunk-WDIWLXLV.js} +3 -15
- package/chunks/{chunk-6YPQGVF4.js → chunk-WIEXQUTD.js} +1 -1
- package/chunks/{chunk-W24BETFG.js → chunk-XAGJJNQW.js} +3 -3
- package/chunks/{chunk-2DSVF5AD.js → chunk-ZGNDXPLU.js} +3 -3
- package/chunks/{chunk-XEDGMZJD.js → chunk-ZGVZU6L2.js} +81 -25
- package/chunks/{chunk-QXQZVEDC.js → chunk-ZKJPLWRJ.js} +2 -2
- package/chunks/{chunk-MLSZVVTT.js → chunk-ZYBLQ5CT.js} +13 -7
- package/chunks/{create.action-P6DLCK4W.js → create.action-DBNIS665.js} +21 -19
- package/chunks/{delete.action-HJKRRHE2.js → delete.action-GBOZC45K.js} +21 -19
- package/chunks/{delete.action-Z3GAA4ZN.js → delete.action-K7BLK7DK.js} +21 -19
- package/chunks/{get.action-IT4EHAV4.js → get.action-N3JOY3OU.js} +17 -12
- package/chunks/get.action-QHKMYZBK.js +91 -0
- package/chunks/{list.action-WLIAO5UW.js → list.action-6SSO3JVN.js} +45 -15
- package/chunks/{list.action-2FU5UZNH.js → list.action-TJCS6UEY.js} +41 -21
- package/chunks/{publish.action-T4J4DRXR.js → publish.action-T24VHRMR.js} +29 -24
- package/chunks/query-WKATAJJ6.js +129 -0
- package/chunks/scripts-VIBLGKYG.js +102 -0
- package/chunks/{update.action-3OVS3HWC.js → update.action-OGYNBXRU.js} +24 -19
- package/chunks/{update.action-MY7QPSSU.js → update.action-VOE6PH5F.js} +24 -19
- package/docs.html +1363 -320
- package/index.js +417 -174
- package/package.json +14 -13
- package/skills/scalar-cli/SKILL.md +13 -1
- package/template.md +157 -15
- package/chunks/action-JAHFRYWZ.js +0 -423
- package/chunks/action-N7BA5I3E.js +0 -229
- package/chunks/chunk-CWCETP6H.js +0 -610
- package/chunks/chunk-K74E42RV.js +0 -7311
package/README.md
CHANGED
|
@@ -15,6 +15,23 @@ Command-line interface to work with OpenAPI files
|
|
|
15
15
|
- Preview your API reference
|
|
16
16
|
- Bundle multiple OpenAPI files
|
|
17
17
|
|
|
18
|
+
## Projects
|
|
19
|
+
|
|
20
|
+
Discover project slugs and inspect project details without opening the Dashboard:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
scalar auth login
|
|
24
|
+
scalar project list
|
|
25
|
+
scalar project get my-docs
|
|
26
|
+
scalar project deployments list --slug my-docs
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
These commands use your existing login and current team. The list includes unified docs projects and legacy sync or unlinked projects, with migrated projects shown once. Older Dashboard editor projects are not included.
|
|
30
|
+
|
|
31
|
+
Use `scalar project list --json` for an array of project details and `scalar project get my-docs --json` for one object. Both include `uid`, `name`, `slug`, `provider`, `isPrivate`, `repository`, and `activeDeployment`. An unlinked repository or absent live deployment is `null`; the provider is `forgejo`, `github`, `bitbucket`, or `unlinked`. The live deployment describes the active build, not a failed or pending publish attempt.
|
|
32
|
+
|
|
33
|
+
Project listing retrieves every page. On older servers that truncate the list without a continuation cursor, it exits with an error instead of printing an incomplete list. Errors go to stderr and exit nonzero.
|
|
34
|
+
|
|
18
35
|
## Documentation
|
|
19
36
|
|
|
20
37
|
This is an overview + API Reference of the CLI, if you want guides on how to use the CLI in more detail go to our [Docs](https://guides.scalar.com/scalar/scalar-cli)
|
|
@@ -77,6 +94,55 @@ npx @scalar/cli help
|
|
|
77
94
|
pnpm dlx @scalar/cli help
|
|
78
95
|
```
|
|
79
96
|
|
|
97
|
+
## Shell completion
|
|
98
|
+
|
|
99
|
+
Generate completions for Bash, Zsh, or Fish with the installed CLI on PATH. These instructions work for both `npm -g install @scalar/cli` and the standalone installer. Completion runs locally, needs no login or network access, and discovers commands, nested commands, flags, and finite option values from the installed CLI. File arguments and file options retain native filesystem completion.
|
|
100
|
+
|
|
101
|
+
### Bash
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
mkdir -p ~/.local/share/scalar
|
|
105
|
+
scalar completion bash > ~/.local/share/scalar/completion.bash
|
|
106
|
+
source ~/.local/share/scalar/completion.bash
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Add `source ~/.local/share/scalar/completion.bash` to `~/.bashrc`, or `~/.bash_profile` for a macOS login shell. Bash 3.2 and newer are supported. The script registers both `scalar` and `scalar-cli`.
|
|
110
|
+
|
|
111
|
+
### Zsh
|
|
112
|
+
|
|
113
|
+
```zsh
|
|
114
|
+
mkdir -p ~/.zsh/completions
|
|
115
|
+
scalar completion zsh > ~/.zsh/completions/_scalar
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Add the following to `~/.zshrc`, placing the `fpath` line before your existing `compinit` setup. If your shell already initializes completion, keep that setup instead of calling `compinit` twice.
|
|
119
|
+
|
|
120
|
+
```zsh
|
|
121
|
+
fpath=(~/.zsh/completions $fpath)
|
|
122
|
+
autoload -Uz compinit
|
|
123
|
+
compinit
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Open a new shell. Both `scalar` and `scalar-cli` use the same completion function.
|
|
127
|
+
|
|
128
|
+
### Fish
|
|
129
|
+
|
|
130
|
+
```fish
|
|
131
|
+
mkdir -p ~/.config/fish/completions
|
|
132
|
+
scalar completion fish > ~/.config/fish/completions/scalar.fish
|
|
133
|
+
cp ~/.config/fish/completions/scalar.fish ~/.config/fish/completions/scalar-cli.fish
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Open a new shell. The second file enables autoloading when using `scalar-cli`; it is optional for standalone installs that only provide `scalar`.
|
|
137
|
+
|
|
138
|
+
### Upgrades and removal
|
|
139
|
+
|
|
140
|
+
Completion reads the installed executable's command definitions on each Tab press, so new commands and options appear after an upgrade. Regenerate your script by repeating the generation command with `>` after upgrading with npm or re-running the standalone installer, then open a new shell. This also refreshes any improvements to the shell adapter. Avoid appending scripts with `>>`.
|
|
141
|
+
|
|
142
|
+
To remove completion, delete the generated file (both files for Fish) and remove the `source` line for Bash or the Scalar `fpath` entry for Zsh, then open a new shell. Keep shared `compinit` setup used by other tools.
|
|
143
|
+
|
|
144
|
+
These scripts target installed `scalar` and `scalar-cli` executables, not `npx` or `pnpm dlx` invocations. If Git's unrelated `scalar` executable takes precedence on PATH, use npm's `scalar-cli` alias or correct your PATH before installing completions. Standalone installations provide `scalar`.
|
|
145
|
+
|
|
80
146
|
## API Reference configuration
|
|
81
147
|
|
|
82
148
|
Pass API Reference options as a JSON object:
|
|
@@ -106,6 +172,19 @@ precedence over `--token`. Unset it to use a different explicit token.
|
|
|
106
172
|
Supply required options in automation instead of relying on interactive prompts.
|
|
107
173
|
For example, pass `--output` for document transformations.
|
|
108
174
|
|
|
175
|
+
## Team discovery
|
|
176
|
+
|
|
177
|
+
After logging in, run `scalar team list` to see your teams and their copyable UIDs. The current team is marked as the default. Use a UID with `scalar team set --team <uid>` to switch teams.
|
|
178
|
+
|
|
179
|
+
Run `scalar team get` to see the current team's UID, name, slug, and namespaces. Both discovery commands support `--json` for scripts:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
scalar team list --json
|
|
183
|
+
scalar team get --json
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`team list --json` returns an array of `{ uid, name, current }` objects. `team get --json` returns `{ uid, name, slug, namespaces }`. Empty lists and namespace arrays remain empty arrays in JSON output. Personal-token logins can inspect their current team, but switching teams still requires logging in with a token for that team.
|
|
187
|
+
|
|
109
188
|
## Commands
|
|
110
189
|
|
|
111
190
|
```
|
|
@@ -114,21 +193,23 @@ Usage: scalar [options] [command]
|
|
|
114
193
|
CLI to work with your OpenAPI files
|
|
115
194
|
|
|
116
195
|
Options:
|
|
117
|
-
-v, --version
|
|
118
|
-
-h, --help
|
|
196
|
+
-v, --version output the version number
|
|
197
|
+
-h, --help display help for command
|
|
119
198
|
|
|
120
199
|
Commands:
|
|
121
|
-
readme
|
|
122
|
-
upgrade
|
|
123
|
-
context
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
200
|
+
readme Open documentation for the CLI
|
|
201
|
+
upgrade Upgrade current version of your cli
|
|
202
|
+
context Print every command, argument, and option as JSON for AI agents
|
|
203
|
+
completion <shell> Generate shell completion definitions
|
|
204
|
+
auth Manage authorization on scalar platform
|
|
205
|
+
access-group Manage access groups and allowed email domains for the current team
|
|
206
|
+
document Manage local openapi file
|
|
207
|
+
project Manage scalar project
|
|
208
|
+
registry Manage your scalar registry
|
|
209
|
+
team Manage user teams
|
|
210
|
+
sdk Manage your Scalar SDKs (Enterprise Only)
|
|
211
|
+
schema Manage your Scalar schemas
|
|
212
|
+
help [command] display help for command
|
|
132
213
|
```
|
|
133
214
|
|
|
134
215
|
### readme
|
|
@@ -175,6 +256,19 @@ Options:
|
|
|
175
256
|
-h, --help display help for command
|
|
176
257
|
```
|
|
177
258
|
|
|
259
|
+
### completion
|
|
260
|
+
```
|
|
261
|
+
Usage: scalar completion [options] <shell>
|
|
262
|
+
|
|
263
|
+
Generate shell completion definitions
|
|
264
|
+
|
|
265
|
+
Arguments:
|
|
266
|
+
shell Shell to configure (choices: "bash", "zsh", "fish")
|
|
267
|
+
|
|
268
|
+
Options:
|
|
269
|
+
-h, --help display help for command
|
|
270
|
+
```
|
|
271
|
+
|
|
178
272
|
### auth
|
|
179
273
|
```
|
|
180
274
|
Usage: scalar auth [options] [command]
|
|
@@ -198,10 +292,8 @@ Usage: scalar auth login [options]
|
|
|
198
292
|
Login to scalar
|
|
199
293
|
|
|
200
294
|
Options:
|
|
201
|
-
--
|
|
202
|
-
--
|
|
203
|
-
--token <token> Personal token
|
|
204
|
-
-h, --help display help for command
|
|
295
|
+
--token <token> Personal token
|
|
296
|
+
-h, --help display help for command
|
|
205
297
|
```
|
|
206
298
|
|
|
207
299
|
#### whoami
|
|
@@ -224,6 +316,144 @@ Options:
|
|
|
224
316
|
-h, --help display help for command
|
|
225
317
|
```
|
|
226
318
|
|
|
319
|
+
### access-group
|
|
320
|
+
```
|
|
321
|
+
Usage: scalar access-group [options] [command]
|
|
322
|
+
|
|
323
|
+
Manage access groups and allowed email domains for the current team
|
|
324
|
+
|
|
325
|
+
Options:
|
|
326
|
+
-h, --help display help for command
|
|
327
|
+
|
|
328
|
+
Commands:
|
|
329
|
+
list [options] List access groups for the current team
|
|
330
|
+
create [options] <slug> Create an access group (Pro or above)
|
|
331
|
+
get [options] <slug> Get an access group and its allowlists
|
|
332
|
+
update [options] <slug> Update access group metadata
|
|
333
|
+
delete [options] <slug> Delete an access group and remove its project
|
|
334
|
+
assignments
|
|
335
|
+
domain Manage allowed email domains
|
|
336
|
+
help [command] display help for command
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
#### list
|
|
340
|
+
```
|
|
341
|
+
Usage: scalar access-group list [options]
|
|
342
|
+
|
|
343
|
+
List access groups for the current team
|
|
344
|
+
|
|
345
|
+
Options:
|
|
346
|
+
--json Print the result as JSON
|
|
347
|
+
-h, --help display help for command
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
#### create
|
|
351
|
+
```
|
|
352
|
+
Usage: scalar access-group create [options] <slug>
|
|
353
|
+
|
|
354
|
+
Create an access group (Pro or above)
|
|
355
|
+
|
|
356
|
+
Arguments:
|
|
357
|
+
slug New access group slug
|
|
358
|
+
|
|
359
|
+
Options:
|
|
360
|
+
--name <name> Display name
|
|
361
|
+
--domain <domains...> Allowed email domains
|
|
362
|
+
--json Print the result as JSON
|
|
363
|
+
-h, --help display help for command
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
#### get
|
|
367
|
+
```
|
|
368
|
+
Usage: scalar access-group get [options] <slug>
|
|
369
|
+
|
|
370
|
+
Get an access group and its allowlists
|
|
371
|
+
|
|
372
|
+
Arguments:
|
|
373
|
+
slug Access group slug
|
|
374
|
+
|
|
375
|
+
Options:
|
|
376
|
+
--json Print the result as JSON
|
|
377
|
+
-h, --help display help for command
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
#### update
|
|
381
|
+
```
|
|
382
|
+
Usage: scalar access-group update [options] <slug>
|
|
383
|
+
|
|
384
|
+
Update access group metadata
|
|
385
|
+
|
|
386
|
+
Arguments:
|
|
387
|
+
slug Current access group slug
|
|
388
|
+
|
|
389
|
+
Options:
|
|
390
|
+
--name <name> New display name
|
|
391
|
+
--new-slug <slug> New access group slug
|
|
392
|
+
--json Print the result as JSON
|
|
393
|
+
-h, --help display help for command
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
#### delete
|
|
397
|
+
```
|
|
398
|
+
Usage: scalar access-group delete [options] <slug>
|
|
399
|
+
|
|
400
|
+
Delete an access group and remove its project assignments
|
|
401
|
+
|
|
402
|
+
Arguments:
|
|
403
|
+
slug Access group slug
|
|
404
|
+
|
|
405
|
+
Options:
|
|
406
|
+
-y, --yes Confirm deletion without prompting
|
|
407
|
+
--json Print the result as JSON (requires --yes)
|
|
408
|
+
-h, --help display help for command
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
#### domain
|
|
412
|
+
```
|
|
413
|
+
Usage: scalar access-group domain [options] [command]
|
|
414
|
+
|
|
415
|
+
Manage allowed email domains
|
|
416
|
+
|
|
417
|
+
Options:
|
|
418
|
+
-h, --help display help for command
|
|
419
|
+
|
|
420
|
+
Commands:
|
|
421
|
+
add [options] <slug> <domain> Add an exact email domain to an access group
|
|
422
|
+
remove [options] <slug> <domain> Remove an exact email domain from an access
|
|
423
|
+
group
|
|
424
|
+
help [command] display help for command
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
##### add
|
|
428
|
+
```
|
|
429
|
+
Usage: scalar access-group domain add [options] <slug> <domain>
|
|
430
|
+
|
|
431
|
+
Add an exact email domain to an access group
|
|
432
|
+
|
|
433
|
+
Arguments:
|
|
434
|
+
slug Access group slug
|
|
435
|
+
domain Email domain, such as example.com
|
|
436
|
+
|
|
437
|
+
Options:
|
|
438
|
+
--json Print the result as JSON
|
|
439
|
+
-h, --help display help for command
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
##### remove
|
|
443
|
+
```
|
|
444
|
+
Usage: scalar access-group domain remove [options] <slug> <domain>
|
|
445
|
+
|
|
446
|
+
Remove an exact email domain from an access group
|
|
447
|
+
|
|
448
|
+
Arguments:
|
|
449
|
+
slug Access group slug
|
|
450
|
+
domain Email domain, such as example.com
|
|
451
|
+
|
|
452
|
+
Options:
|
|
453
|
+
--json Print the result as JSON
|
|
454
|
+
-h, --help display help for command
|
|
455
|
+
```
|
|
456
|
+
|
|
227
457
|
### document
|
|
228
458
|
```
|
|
229
459
|
Usage: scalar document [options] [command]
|
|
@@ -234,19 +464,27 @@ Options:
|
|
|
234
464
|
-h, --help display help for command
|
|
235
465
|
|
|
236
466
|
Commands:
|
|
237
|
-
bundle [options] [file|url] Bundle an OpenAPI document by resolving all
|
|
238
|
-
|
|
239
|
-
|
|
467
|
+
bundle [options] [file|url] Bundle an OpenAPI document by resolving all
|
|
468
|
+
references and external dependencies
|
|
469
|
+
split [options] [file|url] Split OpenAPI or AsyncAPI documents into small
|
|
470
|
+
chunks
|
|
471
|
+
join [options] <files...> Merge multiple OpenAPI or AsyncAPI documents
|
|
472
|
+
into a single unified document
|
|
240
473
|
format [options] [file|url] Format an OpenAPI or AsyncAPI file
|
|
241
|
-
convert [options] [file|url] Convert a Postman collection to an OpenAPI
|
|
474
|
+
convert [options] [file|url] Convert a Postman collection to an OpenAPI
|
|
475
|
+
document
|
|
242
476
|
markdown [options] [file|url] Generate Markdown from an OpenAPI file
|
|
243
|
-
mock [options] [file|url] Mock an OpenAPI API or AsyncAPI WebSocket and
|
|
244
|
-
|
|
477
|
+
mock [options] [file|url] Mock an OpenAPI API or AsyncAPI WebSocket and
|
|
478
|
+
SSE channels
|
|
479
|
+
serve [options] [file|url] Serve an API Reference from an OpenAPI or
|
|
480
|
+
AsyncAPI file
|
|
245
481
|
share [options] [file] Share an OpenAPI or AsyncAPI file
|
|
246
482
|
validate [file|url] Validate an OpenAPI or AsyncAPI file
|
|
247
483
|
void [options] Boot a server to mirror HTTP requests
|
|
248
|
-
lint [options] [file|url] Lint your OpenAPI or AsyncAPI file using
|
|
249
|
-
|
|
484
|
+
lint [options] [file|url] Lint your OpenAPI or AsyncAPI file using
|
|
485
|
+
spectral rules
|
|
486
|
+
upgrade [options] [file|url] Upgrade an OpenAPI or AsyncAPI document to
|
|
487
|
+
version 3.1
|
|
250
488
|
help [command] display help for command
|
|
251
489
|
```
|
|
252
490
|
|
|
@@ -263,7 +501,8 @@ Options:
|
|
|
263
501
|
-o, --output <file> Path to save the bundled output file
|
|
264
502
|
--treeShake Remove unused components from the bundled output
|
|
265
503
|
--urlMap Generate a map of resolved URLs in the bundled output
|
|
266
|
-
--fetchLimit <limit> Maximum number of URLs to fetch during bundling at the
|
|
504
|
+
--fetchLimit <limit> Maximum number of URLs to fetch during bundling at the
|
|
505
|
+
same time
|
|
267
506
|
-h, --help display help for command
|
|
268
507
|
```
|
|
269
508
|
|
|
@@ -288,12 +527,12 @@ Usage: scalar document join [options] <files...>
|
|
|
288
527
|
Merge multiple OpenAPI or AsyncAPI documents into a single unified document
|
|
289
528
|
|
|
290
529
|
Arguments:
|
|
291
|
-
files
|
|
530
|
+
files Paths to the OpenAPI or AsyncAPI files to merge
|
|
292
531
|
|
|
293
532
|
Options:
|
|
294
|
-
--output
|
|
295
|
-
--prefix-components-with-path-value
|
|
296
|
-
-h, --help
|
|
533
|
+
-o, --output <file> Path to save the merged output file
|
|
534
|
+
-p, --prefix-components-with-path-value <path> Dot-separated path to extract a prefix value from each input file for component names
|
|
535
|
+
-h, --help display help for command
|
|
297
536
|
```
|
|
298
537
|
|
|
299
538
|
#### format
|
|
@@ -418,11 +657,20 @@ Usage: scalar document lint [options] [file|url]
|
|
|
418
657
|
Lint your OpenAPI or AsyncAPI file using spectral rules
|
|
419
658
|
|
|
420
659
|
Arguments:
|
|
421
|
-
file|url
|
|
660
|
+
file|url OpenAPI or AsyncAPI file path or url
|
|
422
661
|
|
|
423
662
|
Options:
|
|
424
|
-
-r, --rule <file|url>
|
|
425
|
-
|
|
663
|
+
-r, --rule <file|url> Rule path or url
|
|
664
|
+
--format <format> Report format (choices: "text", "codeframe",
|
|
665
|
+
"markdown", "summary", "json", "github-actions",
|
|
666
|
+
"junit", default: "codeframe")
|
|
667
|
+
--max-problems <number> Maximum displayed findings (totals and exit status
|
|
668
|
+
include all findings) (default: 100)
|
|
669
|
+
-o, --output <file> Write the report to a file instead of stdout
|
|
670
|
+
--generate-ignore-file Record current findings in the ignore baseline
|
|
671
|
+
--ignore-file <file> Ignore baseline path (Scalar file takes priority over
|
|
672
|
+
Redocly fallback in the current directory)
|
|
673
|
+
-h, --help display help for command
|
|
426
674
|
```
|
|
427
675
|
|
|
428
676
|
#### upgrade
|
|
@@ -449,17 +697,48 @@ Options:
|
|
|
449
697
|
-h, --help display help for command
|
|
450
698
|
|
|
451
699
|
Commands:
|
|
700
|
+
list [options] List projects and their slugs for the current
|
|
701
|
+
team.
|
|
702
|
+
get [options] <slug> Get project details for the current team.
|
|
452
703
|
init [options] Create a new Scalar Docs project.
|
|
453
704
|
check-config [file] Check a Scalar Configuration file
|
|
454
|
-
create [options] Create a new project that is not linked to a
|
|
705
|
+
create [options] Create a new project that is not linked to a
|
|
706
|
+
github project.
|
|
455
707
|
preview [options] [config] Preview scalar guides
|
|
456
|
-
publish [options] Publish new build for a github sync project that
|
|
457
|
-
|
|
708
|
+
publish [options] Publish new build for a github sync project that
|
|
709
|
+
is not linked.
|
|
710
|
+
rollback [options] Roll the live deployment back to a previously
|
|
711
|
+
deployed build.
|
|
458
712
|
deployments Inspect a project deployment history.
|
|
459
713
|
upgrade [config] Upgrade scalar project
|
|
460
714
|
help [command] display help for command
|
|
461
715
|
```
|
|
462
716
|
|
|
717
|
+
#### list
|
|
718
|
+
```
|
|
719
|
+
Usage: scalar project list [options]
|
|
720
|
+
|
|
721
|
+
List projects and their slugs for the current team.
|
|
722
|
+
|
|
723
|
+
Options:
|
|
724
|
+
--json Print project details as JSON
|
|
725
|
+
-h, --help display help for command
|
|
726
|
+
```
|
|
727
|
+
|
|
728
|
+
#### get
|
|
729
|
+
```
|
|
730
|
+
Usage: scalar project get [options] <slug>
|
|
731
|
+
|
|
732
|
+
Get project details for the current team.
|
|
733
|
+
|
|
734
|
+
Arguments:
|
|
735
|
+
slug Project slug from scalar project list
|
|
736
|
+
|
|
737
|
+
Options:
|
|
738
|
+
--json Print project details as JSON
|
|
739
|
+
-h, --help display help for command
|
|
740
|
+
```
|
|
741
|
+
|
|
463
742
|
#### init
|
|
464
743
|
```
|
|
465
744
|
Usage: scalar project init [options]
|
|
@@ -504,12 +783,17 @@ Usage: scalar project preview [options] [config]
|
|
|
504
783
|
Preview scalar guides
|
|
505
784
|
|
|
506
785
|
Arguments:
|
|
507
|
-
config Path to the Scalar configuration file (usually
|
|
786
|
+
config Path to the Scalar configuration file (usually
|
|
787
|
+
`scalar.config.json5` or `scalar.config.json`)
|
|
508
788
|
|
|
509
789
|
Options:
|
|
510
|
-
-p, --port [port] port to run the server on. If the port is not
|
|
511
|
-
|
|
512
|
-
|
|
790
|
+
-p, --port [port] port to run the server on. If the port is not
|
|
791
|
+
available, it will select another one. (default:
|
|
792
|
+
"7970")
|
|
793
|
+
-H, --host [host] Specify which IP addresses the server should listen
|
|
794
|
+
on.
|
|
795
|
+
-L, --log-level <level> Set the log level (choices: "debug", "info", default:
|
|
796
|
+
"info")
|
|
513
797
|
-N, --no-open Do not open the browser automatically
|
|
514
798
|
-h, --help display help for command
|
|
515
799
|
```
|
|
@@ -521,7 +805,7 @@ Usage: scalar project publish [options]
|
|
|
521
805
|
Publish new build for a github sync project that is not linked.
|
|
522
806
|
|
|
523
807
|
Options:
|
|
524
|
-
-s, --slug [slug] Project slug
|
|
808
|
+
-s, --slug [slug] Project slug from scalar project list
|
|
525
809
|
-c, --config [config] Your config file of the project
|
|
526
810
|
-p, --preview Publish in preview mode
|
|
527
811
|
-g, --github Publish from your linked remote GitHub repository
|
|
@@ -535,8 +819,9 @@ Usage: scalar project rollback [options]
|
|
|
535
819
|
Roll the live deployment back to a previously deployed build.
|
|
536
820
|
|
|
537
821
|
Options:
|
|
538
|
-
-s, --slug [slug] Project slug
|
|
539
|
-
-t, --to <publishUid> Roll back to a specific build id (defaults to the next
|
|
822
|
+
-s, --slug [slug] Project slug from scalar project list
|
|
823
|
+
-t, --to <publishUid> Roll back to a specific build id (defaults to the next
|
|
824
|
+
older deployed build)
|
|
540
825
|
-y, --yes Skip the confirmation prompt
|
|
541
826
|
-h, --help display help for command
|
|
542
827
|
```
|
|
@@ -562,7 +847,7 @@ Usage: scalar project deployments list [options]
|
|
|
562
847
|
List the production deployment history for a project.
|
|
563
848
|
|
|
564
849
|
Options:
|
|
565
|
-
-s, --slug [slug] Project slug
|
|
850
|
+
-s, --slug [slug] Project slug from scalar project list
|
|
566
851
|
-h, --help display help for command
|
|
567
852
|
```
|
|
568
853
|
|
|
@@ -573,7 +858,8 @@ Usage: scalar project upgrade [options] [config]
|
|
|
573
858
|
Upgrade scalar project
|
|
574
859
|
|
|
575
860
|
Arguments:
|
|
576
|
-
config Path to the Scalar configuration file (usually
|
|
861
|
+
config Path to the Scalar configuration file (usually
|
|
862
|
+
`scalar.config.json5` or `scalar.config.json`)
|
|
577
863
|
|
|
578
864
|
Options:
|
|
579
865
|
-h, --help display help for command
|
|
@@ -589,11 +875,15 @@ Options:
|
|
|
589
875
|
-h, --help display help for command
|
|
590
876
|
|
|
591
877
|
Commands:
|
|
592
|
-
publish [options] [file] Publish an OpenAPI document to the Scalar
|
|
593
|
-
|
|
878
|
+
publish [options] [file] Publish an OpenAPI document to the Scalar
|
|
879
|
+
registry
|
|
880
|
+
update [options] [namespace] [slug] Update document metadata on scalar
|
|
881
|
+
registry
|
|
594
882
|
delete [namespace] [slug] Delete a document from scalar registry
|
|
595
|
-
list [options] List all registry APIs for a team
|
|
596
|
-
|
|
883
|
+
list [options] List all registry APIs for a team
|
|
884
|
+
namespace
|
|
885
|
+
get [options] [namespace] [slug] Get a document version from scalar
|
|
886
|
+
registry
|
|
597
887
|
help [command] display help for command
|
|
598
888
|
```
|
|
599
889
|
|
|
@@ -607,7 +897,8 @@ Arguments:
|
|
|
607
897
|
file OpenAPI file to upload
|
|
608
898
|
|
|
609
899
|
Options:
|
|
610
|
-
--slug <slug> Slug identifier for the registry entry. Defaults to
|
|
900
|
+
--slug <slug> Slug identifier for the registry entry. Defaults to
|
|
901
|
+
title.
|
|
611
902
|
--namespace <namespace> Scalar team namespace
|
|
612
903
|
--version <version> API version (e.g. 0.1.0)
|
|
613
904
|
--private Make API private (default: false)
|
|
@@ -615,8 +906,10 @@ Options:
|
|
|
615
906
|
--force Force override an existing version (default: false)
|
|
616
907
|
--bundle Bundle all external references before uploading
|
|
617
908
|
--treeShake Remove unused components from the bundled document
|
|
618
|
-
--urlMap Generate a map of resolved URLs when bundling the
|
|
619
|
-
|
|
909
|
+
--urlMap Generate a map of resolved URLs when bundling the
|
|
910
|
+
document
|
|
911
|
+
--fetchLimit <limit> Maximum number of concurrent URLs to fetch when
|
|
912
|
+
bundling the document
|
|
620
913
|
-h, --help display help for command
|
|
621
914
|
```
|
|
622
915
|
|
|
@@ -658,6 +951,7 @@ List all registry APIs for a team namespace
|
|
|
658
951
|
|
|
659
952
|
Options:
|
|
660
953
|
--namespace <namespace> Team namespace
|
|
954
|
+
--json Output registry API metadata as JSON
|
|
661
955
|
-h, --help display help for command
|
|
662
956
|
```
|
|
663
957
|
|
|
@@ -673,7 +967,7 @@ Arguments:
|
|
|
673
967
|
|
|
674
968
|
Options:
|
|
675
969
|
--version <version> Document version (defaults to latest)
|
|
676
|
-
--format <format> Output format (json or yaml) (default: "json")
|
|
970
|
+
--format <format> Output format (json or yaml) (choices: "json", "yaml", default: "json")
|
|
677
971
|
-o, --output <file> Output file (defaults to stdout)
|
|
678
972
|
-h, --help display help for command
|
|
679
973
|
```
|
|
@@ -688,7 +982,8 @@ Options:
|
|
|
688
982
|
-h, --help display help for command
|
|
689
983
|
|
|
690
984
|
Commands:
|
|
691
|
-
list
|
|
985
|
+
list [options] List all teams current user is part of
|
|
986
|
+
get [options] Get the current team and its namespaces
|
|
692
987
|
set [options] Set current active team for the user
|
|
693
988
|
help [command] display help for command
|
|
694
989
|
```
|
|
@@ -700,6 +995,18 @@ Usage: scalar team list [options]
|
|
|
700
995
|
List all teams current user is part of
|
|
701
996
|
|
|
702
997
|
Options:
|
|
998
|
+
--json Output teams as JSON
|
|
999
|
+
-h, --help display help for command
|
|
1000
|
+
```
|
|
1001
|
+
|
|
1002
|
+
#### get
|
|
1003
|
+
```
|
|
1004
|
+
Usage: scalar team get [options]
|
|
1005
|
+
|
|
1006
|
+
Get the current team and its namespaces
|
|
1007
|
+
|
|
1008
|
+
Options:
|
|
1009
|
+
--json Output the current team as JSON
|
|
703
1010
|
-h, --help display help for command
|
|
704
1011
|
```
|
|
705
1012
|
|
|
@@ -725,7 +1032,9 @@ Options:
|
|
|
725
1032
|
|
|
726
1033
|
Commands:
|
|
727
1034
|
list [options] List all SDKs for a team namespace
|
|
728
|
-
|
|
1035
|
+
get [options] Inspect SDK metadata, API source, versions, and build status
|
|
1036
|
+
create [options] Create a new SDK. The SDK is created in the namespace of the
|
|
1037
|
+
API it is built from.
|
|
729
1038
|
update [options] Update SDK metadata.
|
|
730
1039
|
delete [options] Delete an SDK.
|
|
731
1040
|
build [options] Build an SDK.
|
|
@@ -739,20 +1048,37 @@ Usage: scalar sdk list [options]
|
|
|
739
1048
|
List all SDKs for a team namespace
|
|
740
1049
|
|
|
741
1050
|
Options:
|
|
1051
|
+
--json Output structured SDK metadata as JSON
|
|
742
1052
|
--namespace <namespace> Team namespace
|
|
743
1053
|
-h, --help display help for command
|
|
744
1054
|
```
|
|
745
1055
|
|
|
1056
|
+
#### get
|
|
1057
|
+
```
|
|
1058
|
+
Usage: scalar sdk get [options]
|
|
1059
|
+
|
|
1060
|
+
Inspect SDK metadata, API source, versions, and build status
|
|
1061
|
+
|
|
1062
|
+
Options:
|
|
1063
|
+
-s, --slug <slug> SDK slug
|
|
1064
|
+
-n, --namespace <namespace> Team namespace
|
|
1065
|
+
--json Output structured SDK metadata as JSON
|
|
1066
|
+
-h, --help display help for command
|
|
1067
|
+
```
|
|
1068
|
+
|
|
746
1069
|
#### create
|
|
747
1070
|
```
|
|
748
1071
|
Usage: scalar sdk create [options]
|
|
749
1072
|
|
|
750
|
-
Create a new SDK. The SDK is created in the namespace of the API it is built
|
|
1073
|
+
Create a new SDK. The SDK is created in the namespace of the API it is built
|
|
1074
|
+
from.
|
|
751
1075
|
|
|
752
1076
|
Options:
|
|
753
1077
|
-a, --api <api> Registry API slug
|
|
754
1078
|
-n, --namespace <namespace> Team namespace to look the API up in
|
|
755
|
-
-l, --language <language> Language of your SDK (choices: "typescript",
|
|
1079
|
+
-l, --language <language> Language of your SDK (choices: "typescript",
|
|
1080
|
+
"python", "cli", "csharp", "java", "ruby", "php",
|
|
1081
|
+
"go", "rust", "kotlin", "swift", "cpp", "dart")
|
|
756
1082
|
-h, --help display help for command
|
|
757
1083
|
```
|
|
758
1084
|
|
|
@@ -766,7 +1092,7 @@ Options:
|
|
|
766
1092
|
-s, --slug <slug> SDK slug
|
|
767
1093
|
-n, --namespace <namespace> Team namespace
|
|
768
1094
|
--title <title> Title
|
|
769
|
-
--isPrivate <isPrivate> Privacy (true/false or public/private)
|
|
1095
|
+
--isPrivate <isPrivate> Privacy (true/false or public/private) (choices: "true", "false", "public", "private")
|
|
770
1096
|
-h, --help display help for command
|
|
771
1097
|
```
|
|
772
1098
|
|
|
@@ -807,8 +1133,10 @@ Commands:
|
|
|
807
1133
|
delete [options] Delete a schema.
|
|
808
1134
|
update [options] Update schema metadata.
|
|
809
1135
|
list [options] List all schemas for a team namespace
|
|
810
|
-
get [options] [namespace] [slug] Get a schema document version from the
|
|
811
|
-
|
|
1136
|
+
get [options] [namespace] [slug] Get a schema document version from the
|
|
1137
|
+
Scalar registry
|
|
1138
|
+
publish [options] [file] Publish a shared schema to the Scalar
|
|
1139
|
+
registry
|
|
812
1140
|
help [command] display help for command
|
|
813
1141
|
```
|
|
814
1142
|
|
|
@@ -835,7 +1163,7 @@ Options:
|
|
|
835
1163
|
-n, --namespace <namespace> Team namespace
|
|
836
1164
|
--title <title> Title
|
|
837
1165
|
--description <description> Description
|
|
838
|
-
--isPrivate <isPrivate> Privacy (true/false or public/private)
|
|
1166
|
+
--isPrivate <isPrivate> Privacy (true/false or public/private) (choices: "true", "false", "public", "private")
|
|
839
1167
|
-h, --help display help for command
|
|
840
1168
|
```
|
|
841
1169
|
|
|
@@ -847,6 +1175,7 @@ List all schemas for a team namespace
|
|
|
847
1175
|
|
|
848
1176
|
Options:
|
|
849
1177
|
--namespace <namespace> Team namespace
|
|
1178
|
+
--json Output schema metadata as JSON
|
|
850
1179
|
-h, --help display help for command
|
|
851
1180
|
```
|
|
852
1181
|
|
|
@@ -862,7 +1191,7 @@ Arguments:
|
|
|
862
1191
|
|
|
863
1192
|
Options:
|
|
864
1193
|
--version <version> Schema version (defaults to latest)
|
|
865
|
-
--format <format> Output format (json or yaml) (default: "json")
|
|
1194
|
+
--format <format> Output format (json or yaml) (choices: "json", "yaml", default: "json")
|
|
866
1195
|
-o, --output <file> Output file (defaults to stdout)
|
|
867
1196
|
-h, --help display help for command
|
|
868
1197
|
```
|
|
@@ -877,7 +1206,8 @@ Arguments:
|
|
|
877
1206
|
file OpenAPI file to upload
|
|
878
1207
|
|
|
879
1208
|
Options:
|
|
880
|
-
--slug <slug> Slug identifier for the registry entry. Defaults to
|
|
1209
|
+
--slug <slug> Slug identifier for the registry entry. Defaults to
|
|
1210
|
+
title.
|
|
881
1211
|
--title <title> Schema title
|
|
882
1212
|
--namespace <namespace> Scalar team namespace
|
|
883
1213
|
--version <version> API version (e.g. 0.1.0)
|
|
@@ -885,8 +1215,10 @@ Options:
|
|
|
885
1215
|
--force Force override an existing version (default: false)
|
|
886
1216
|
--bundle Bundle all external references before uploading
|
|
887
1217
|
--treeShake Remove unused components from the bundled document
|
|
888
|
-
--urlMap Generate a map of resolved URLs when bundling the
|
|
889
|
-
|
|
1218
|
+
--urlMap Generate a map of resolved URLs when bundling the
|
|
1219
|
+
document
|
|
1220
|
+
--fetchLimit <limit> Maximum number of concurrent URLs to fetch when
|
|
1221
|
+
bundling the document
|
|
890
1222
|
-h, --help display help for command
|
|
891
1223
|
```
|
|
892
1224
|
|
|
@@ -913,6 +1245,36 @@ cp -r "$(dirname "$(readlink "$(command -v scalar)")")/app/skills/scalar-cli" .c
|
|
|
913
1245
|
|
|
914
1246
|
With the standalone CLI on Windows, the skill is in `%LOCALAPPDATA%\Scalar\current\app\skills\scalar-cli`.
|
|
915
1247
|
|
|
1248
|
+
## Inspect SDKs
|
|
1249
|
+
|
|
1250
|
+
Use your current team login to inspect an SDK by slug. The namespace defaults to the team's first namespace.
|
|
1251
|
+
|
|
1252
|
+
```bash
|
|
1253
|
+
scalar sdk get --slug widgets --namespace acme
|
|
1254
|
+
scalar sdk get --slug widgets --namespace acme --json
|
|
1255
|
+
scalar sdk list --namespace acme --json
|
|
1256
|
+
```
|
|
1257
|
+
|
|
1258
|
+
JSON output is a metadata object for `get` and an array for `list` (including `[]` when empty). It includes the linked registry API, tracked API version, target languages and slugs, current SDK version, version history with active build IDs, and the latest attempted build with per-language generation and Git sync status. The latest attempt may be a different version or have failed; it does not replace the current version or active artifacts. Timestamps are Unix seconds; absent builds and unlinked API sources are `null`. Generator configuration, repository auth bindings, and raw build messages are excluded.
|
|
1259
|
+
|
|
1260
|
+
## Registry metadata for scripts
|
|
1261
|
+
|
|
1262
|
+
Use `scalar registry list --json` to write a JSON array to stdout. Without
|
|
1263
|
+
`--namespace`, the command uses the first namespace of your current team, just
|
|
1264
|
+
like the default table output. You must be logged in; errors go to stderr and
|
|
1265
|
+
exit with a nonzero status.
|
|
1266
|
+
|
|
1267
|
+
```bash
|
|
1268
|
+
scalar registry list --namespace scalar --json > registry-apis.json
|
|
1269
|
+
scalar registry get scalar demo-api --version 1.2.3 > openapi.json
|
|
1270
|
+
```
|
|
1271
|
+
|
|
1272
|
+
Each array entry contains `namespace` and `slug` (the coordinates accepted by
|
|
1273
|
+
`registry get`), `title` (a string, which may be empty), `version` (the current
|
|
1274
|
+
version served by default), and `isPrivate` (a boolean). JSON output includes
|
|
1275
|
+
only these metadata fields, without document content or credentials. An empty
|
|
1276
|
+
namespace returns `[]`. Omit `--json` for the human-readable table.
|
|
1277
|
+
|
|
916
1278
|
## GitHub Actions
|
|
917
1279
|
|
|
918
1280
|
To validate your OpenAPI file in GitHub Actions, add this workflow:
|
|
@@ -944,30 +1306,63 @@ jobs:
|
|
|
944
1306
|
run: npx @scalar/cli document validate ./my-openapi-file.yaml
|
|
945
1307
|
```
|
|
946
1308
|
|
|
947
|
-
##
|
|
1309
|
+
## CI lint reports and baselines
|
|
948
1310
|
|
|
949
|
-
|
|
1311
|
+
Lint reports support CI annotations, test-report viewers, and readable reviews:
|
|
950
1312
|
|
|
951
|
-
```
|
|
952
|
-
|
|
953
|
-
|
|
1313
|
+
```sh
|
|
1314
|
+
scalar document lint openapi.yaml --format codeframe
|
|
1315
|
+
scalar document lint openapi.yaml --format markdown --output lint-results.md
|
|
1316
|
+
scalar document lint openapi.yaml --format summary
|
|
1317
|
+
scalar document lint openapi.yaml --format github-actions
|
|
1318
|
+
scalar document lint openapi.yaml --format json --output lint-results.json
|
|
1319
|
+
scalar document lint openapi.yaml --format junit --output lint-results.xml
|
|
954
1320
|
```
|
|
955
1321
|
|
|
956
|
-
|
|
1322
|
+
The default is `codeframe`, which shows source excerpts with severity colors and highlighted carets when terminal colors are enabled. `NO_COLOR=1` disables colors, and reports saved with `--output` are always plain text. Use `--format text` for the native report. `markdown` produces tables grouped by source, and `summary` counts findings by rule and severity. Machine-readable reports use 1-based locations; text retains engine-native coordinates. Codeframes omit excerpts for unavailable sources.
|
|
957
1323
|
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
1324
|
+
`--max-problems <number>` limits displayed findings to 100 by default. Findings are ordered by severity, with errors first. Use `--max-problems 0` to hide all findings. Counts and the exit status always include every active finding, and baseline generation records all findings regardless of this limit. Summary rule counts cover the displayed findings; its final error/warning totals cover all findings. Truncation notices go to stderr, keeping JSON and XML valid.
|
|
1325
|
+
|
|
1326
|
+
Reports go to stdout unless `--output` is given. Status, upgrade, and truncation notices go to stderr. Reports are written even when lint findings cause a nonzero exit. Both shell redirection and `--output` work:
|
|
1327
|
+
|
|
1328
|
+
```sh
|
|
1329
|
+
scalar document lint openapi.yaml --format json > lint-results.json
|
|
1330
|
+
scalar document lint openapi.yaml --format json --output lint-results.json
|
|
961
1331
|
```
|
|
962
1332
|
|
|
963
|
-
|
|
1333
|
+
Prefer `--output` in scripts when you want Scalar to check the destination against the input, custom ruleset, baseline, and referenced source files (including clean nested references and file aliases). Shell redirection is convenient for piping; the shell opens or truncates the destination before Scalar starts, so Scalar cannot protect that destination. Parent directories for `--output` must already exist.
|
|
1334
|
+
|
|
1335
|
+
JSON follows Redocly's report shape: `totals` contains error, warning, and ignored counts; `version` is the Scalar CLI version; `problems` is the displayed findings array. Each problem includes `ruleId`, `severity` (`error`, `warn`, `info`, or `hint`), `message`, `suggest`, optional rule `reference`, and a `location` array. Locations contain `source.ref`, a JSON `pointer`, and 1-based `start`/`end` positions with `line` and `col`. Local sources are relative to the current directory; URLs remain absolute. Rule IDs and findings still come from Scalar's Vacuum/Spectral engines. Duplicate-operation-ID findings include the participating definitions, including referenced path items and callbacks. Reports preserve additional locations when supplied by the engine; totals and JUnit still count one testcase per finding, and ignore matching uses the primary location, with legacy native paths retained as matching candidates. Scalar does not yet provide Redocly's typo suggestions.
|
|
1336
|
+
|
|
1337
|
+
GitHub Actions reports use error, warning, and notice annotations with start and end positions and available rule documentation links. Local files are relative to `GITHUB_WORKSPACE`, or the current directory outside Actions. Remote sources appear in the message without a repository file attachment. When saved with `--output`, annotations must subsequently be printed to the runner's stdout to become visible.
|
|
1338
|
+
|
|
1339
|
+
JUnit groups findings into suites by source, with one testcase per displayed finding. To match Redocly, lint errors become XML `error` entries, warnings become `failure` entries, and information/hints become `system-out`. Warnings still do not make the lint command exit nonzero, and JUnit viewers classify those testcases as failed. The CLI lint report compatibility workflow verifies this behavior using the Java JUnit viewer in `dorny/test-reporter`. The `Scalar lint totals` suite records full error, warning, ignored, and hidden counts as properties. A clean run produces a valid zero-test report. Configure CI to upload reports even when the lint step fails.
|
|
1340
|
+
|
|
1341
|
+
To adopt linting with existing findings:
|
|
1342
|
+
|
|
1343
|
+
```sh
|
|
1344
|
+
scalar document lint openapi.yaml --generate-ignore-file
|
|
1345
|
+
scalar document lint openapi.yaml --format github-actions
|
|
1346
|
+
```
|
|
1347
|
+
|
|
1348
|
+
Commit the generated `.scalar.lint-ignore.yaml`. Subsequent runs automatically read it from the current directory. `--ignore-file <file>` overrides that location for generation and linting, including an existing `.redocly.lint-ignore.yaml`. Relative paths resolve from the current directory; no parent-directory search is performed. If Scalar's file is absent, linting automatically falls back to `.redocly.lint-ignore.yaml`. You can also rename a Redocly ignore file to `.scalar.lint-ignore.yaml`; Scalar's file always wins when both exist. Generation defaults to Scalar's filename and leaves Redocly's file intact. Scalar does not read `redocly.yaml`.
|
|
1349
|
+
|
|
1350
|
+
For OpenAPI with the default ruleset, imported mappings support the audited Redocly rules `info-contact`, `info-license`, `operation-description`, `operation-operationId`, `operation-operationId-url-safe` (mapped to Scalar's `operation-operationId-valid-in-url`), `no-path-trailing-slash` (`path-keys-no-trailing-slash`), `path-declaration-must-exist` (`path-declarations-must-exist`), `path-not-include-query`, `tag-description`, and `operation-singular-tag`. Missing-field pointers are adapted where the engines report the containing object. This does not enable rules that Scalar's default engine disables. Unsupported rules produce a notice on stderr; only exact Scalar rule/pointer matches apply to those entries. Severity-only overrides of these audited built-in rules retain migration support. Custom definitions, unknown inheritance, and AsyncAPI use exact Scalar identities. Redocly’s `operation-2xx-response` is not mapped to Scalar’s `operation-success-response`, which also accepts 3xx responses. Full custom-rule compatibility would require running Redocly itself.
|
|
1351
|
+
|
|
1352
|
+
The YAML mapping uses Redocly's source → rule → JSON-pointer structure:
|
|
1353
|
+
|
|
1354
|
+
```yaml
|
|
1355
|
+
openapi.yaml:
|
|
1356
|
+
info-description:
|
|
1357
|
+
- '#/info'
|
|
1358
|
+
```
|
|
964
1359
|
|
|
965
|
-
|
|
1360
|
+
Local source paths are relative to the baseline directory. Matching ignores message, severity, and line changes. Mounted reference paths are resolved to physical source pointers, including nested references; older Scalar baselines using native mount paths continue to match. Path-key findings use the key location to distinguish specific path entries. Root pointers use `#`; `/` and `~` in property names use RFC 6901 escaping. Numeric and string path segments with the same pointer identify the same location.
|
|
966
1361
|
|
|
967
|
-
|
|
1362
|
+
Generation records all current findings and exits successfully after writing the baseline. Generation serializes baseline reads and writes to preserve concurrent updates. A leftover `.lock` directory after an interrupted process must be removed only when no generator is running. Regeneration replaces only the selected input document's entries and preserves other inputs, including shared references. Scalar stores input ownership in a YAML comment (`scalar-owners`) that Redocly ignores. Keep that comment to retain shared-reference ownership; without it, imported entries belong to their source file. Manual edits to the mapping take precedence over comment metadata. Legacy Scalar version 1 baselines remain readable and are migrated to this mapping on regeneration.
|
|
968
1363
|
|
|
969
|
-
|
|
1364
|
+
Matched findings are omitted from reports. Only unmatched errors cause exit 1; warnings, information, and hints do not fail lint. Operational failures, malformed baselines, and missing explicitly selected baselines exit nonzero. A missing default baseline is allowed. Multiple findings at the same source/rule/pointer share one entry. Resolved entries remain harmless until regeneration but can suppress a recurrence; array reordering, document renames, or rule changes may produce new identities.
|
|
970
1365
|
|
|
971
|
-
|
|
1366
|
+
### Schema metadata
|
|
972
1367
|
|
|
973
|
-
|
|
1368
|
+
Use `scalar schema list --json` to discover schemas in the current team namespace, or pass `--namespace <namespace>` to choose one. The output is an array of objects with `namespace`, `slug`, `title`, `version`, and `isPrivate`. `version` is the latest semantic version, or `null` when there are no versions. An empty namespace returns `[]`. Schema content is omitted; use `scalar schema get` to download it.
|