@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.
Files changed (94) hide show
  1. package/README.md +475 -80
  2. package/chunks/action-4GZI2M5B.js +62 -0
  3. package/chunks/action-4W5GUGEG.js +63 -0
  4. package/chunks/{action-HJYZCPUN.js → action-5LF4XYHX.js} +10 -7
  5. package/chunks/{action-SRBN7N3R.js → action-5N3P43MD.js} +17 -12
  6. package/chunks/{action-RBOLLIGX.js → action-5RL4NWUZ.js} +17 -17
  7. package/chunks/{action-SNPOOW6S.js → action-657A4K2D.js} +16 -16
  8. package/chunks/{action-EOAVVL52.js → action-7XOHYWYM.js} +11 -14
  9. package/chunks/{action-AQRPFQKI.js → action-CABLS46Q.js} +9 -7
  10. package/chunks/{action-F7A2K74G.js → action-CB55NWAU.js} +9 -13
  11. package/chunks/{action-5SK5NE7E.js → action-DKDRAIKV.js} +11 -14
  12. package/chunks/{action-7PEQXDWT.js → action-DTEO4YNX.js} +127 -20
  13. package/chunks/{action-BAQYJ6UE.js → action-EAUTQ77U.js} +27 -23
  14. package/chunks/{action-QYGOPSTY.js → action-FBRY5JKU.js} +16 -16
  15. package/chunks/{action-VOFDW3U2.js → action-GFLRD7LO.js} +6 -5
  16. package/chunks/{action-LPVITMWA.js → action-GWYYTUTM.js} +4 -3
  17. package/chunks/{action-4NGK5XMD.js → action-HT42NUUX.js} +29 -24
  18. package/chunks/action-JEYDBB3P.js +147 -0
  19. package/chunks/{action-E4YSRFGT.js → action-KDUFU7TZ.js} +11 -13
  20. package/chunks/{action-BRSSC2SR.js → action-LYCNT3KA.js} +29 -10
  21. package/chunks/{action-CA4QYPI6.js → action-OJ2NK25F.js} +4 -8
  22. package/chunks/{action-NVI5DWFP.js → action-PAM2EZ22.js} +4 -8
  23. package/chunks/action-PPTFYZWD.js +1552 -0
  24. package/chunks/{action-OX2566BE.js → action-R4PGILN4.js} +30 -26
  25. package/chunks/{action-CPLH2CQ5.js → action-TOBU74JH.js} +23 -19
  26. package/chunks/action-U2L5DCFG.js +91 -0
  27. package/chunks/{action-H6OUJWWM.js → action-UUL6SWV4.js} +11 -14
  28. package/chunks/{action-T5XMJXPO.js → action-X7BA7PQQ.js} +10 -8
  29. package/chunks/{action-LVDU6YOI.js → action-XLE37MZL.js} +16 -16
  30. package/chunks/{action-BOZNBCNZ.js → action-XOADBXSX.js} +16 -12
  31. package/chunks/{action-SCOXTCPR.js → action-YSVTZVKV.js} +38 -19
  32. package/chunks/{action-YRX6SN5F.js → action-ZFI77WA5.js} +8 -6
  33. package/chunks/{action-ATGZOWSH.js → action-ZKA3RR3S.js} +15 -11
  34. package/chunks/actions-3SAMH7A5.js +182 -0
  35. package/chunks/{agent-ASPV3R5U.js → agent-2ESZI7NO.js} +7 -5
  36. package/chunks/{asyncapi-H4FU6GPC.js → asyncapi-4HGVM3PR.js} +14 -10
  37. package/chunks/{build.action-6V6GXI3X.js → build.action-VBGFGACM.js} +21 -19
  38. package/chunks/chunk-35Z7VTJT.js +453 -0
  39. package/chunks/chunk-36LXIJIZ.js +52 -0
  40. package/chunks/{chunk-BIKOD3SG.js → chunk-43WALAW3.js} +251 -103
  41. package/chunks/{chunk-C2KAWRIX.js → chunk-5ENKYZA4.js} +1 -1
  42. package/chunks/{chunk-ZJVYOZFB.js → chunk-5SMP756H.js} +2 -2
  43. package/chunks/{chunk-5JLVQVKO.js → chunk-6M7TL2G2.js} +146 -148
  44. package/chunks/chunk-6PSYZO3U.js +24 -0
  45. package/chunks/{chunk-ISXH6Q7I.js → chunk-ATNTXKMS.js} +45 -274
  46. package/chunks/{chunk-BDEPNGTO.js → chunk-BIMLCGKS.js} +1 -1
  47. package/chunks/{chunk-HGOD6THU.js → chunk-CWVYOXXM.js} +2 -19
  48. package/chunks/chunk-DFOZG7ZV.js +15 -0
  49. package/chunks/chunk-DHZW7Q7U.js +133 -0
  50. package/chunks/{chunk-R5LK6VPY.js → chunk-G4HRW2FZ.js} +13 -20
  51. package/chunks/{chunk-KCCFN4F7.js → chunk-GLWTVLKM.js} +29 -29
  52. package/chunks/{chunk-5UHLAJQD.js → chunk-GYRQPDTK.js} +24 -10
  53. package/chunks/chunk-H467HDVV.js +24 -0
  54. package/chunks/chunk-IPZP3VRA.js +327 -0
  55. package/chunks/{chunk-LG7IFACX.js → chunk-JXGF5EHC.js} +152 -18
  56. package/chunks/chunk-K2HIB5BA.js +92 -0
  57. package/chunks/{chunk-FDC2IESH.js → chunk-KHF2QXBG.js} +1352 -8327
  58. package/chunks/{chunk-IMG35UXX.js → chunk-KZNRQVMY.js} +1 -1
  59. package/chunks/{chunk-OJ2EWIJH.js → chunk-MC4EMNOR.js} +5 -1
  60. package/chunks/{chunk-YILQODZF.js → chunk-MMWSCTDB.js} +7 -4
  61. package/chunks/{chunk-6XWCMJDB.js → chunk-MNNGUUKJ.js} +12 -11
  62. package/chunks/chunk-NAC63XJF.js +10 -0
  63. package/chunks/{chunk-XXSQUBXS.js → chunk-UDBSV3CK.js} +107 -453
  64. package/chunks/{chunk-IKT5F47M.js → chunk-VVRUSQCY.js} +11 -11
  65. package/chunks/{chunk-2PPRO2QB.js → chunk-VYFGRLVQ.js} +1 -1
  66. package/chunks/{chunk-GPNB7ISG.js → chunk-WB6PWTMU.js} +5 -13
  67. package/chunks/{chunk-4X47MN6Q.js → chunk-WDIWLXLV.js} +3 -15
  68. package/chunks/{chunk-6YPQGVF4.js → chunk-WIEXQUTD.js} +1 -1
  69. package/chunks/{chunk-W24BETFG.js → chunk-XAGJJNQW.js} +3 -3
  70. package/chunks/{chunk-2DSVF5AD.js → chunk-ZGNDXPLU.js} +3 -3
  71. package/chunks/{chunk-XEDGMZJD.js → chunk-ZGVZU6L2.js} +81 -25
  72. package/chunks/{chunk-QXQZVEDC.js → chunk-ZKJPLWRJ.js} +2 -2
  73. package/chunks/{chunk-MLSZVVTT.js → chunk-ZYBLQ5CT.js} +13 -7
  74. package/chunks/{create.action-P6DLCK4W.js → create.action-DBNIS665.js} +21 -19
  75. package/chunks/{delete.action-HJKRRHE2.js → delete.action-GBOZC45K.js} +21 -19
  76. package/chunks/{delete.action-Z3GAA4ZN.js → delete.action-K7BLK7DK.js} +21 -19
  77. package/chunks/{get.action-IT4EHAV4.js → get.action-N3JOY3OU.js} +17 -12
  78. package/chunks/get.action-QHKMYZBK.js +91 -0
  79. package/chunks/{list.action-WLIAO5UW.js → list.action-6SSO3JVN.js} +45 -15
  80. package/chunks/{list.action-2FU5UZNH.js → list.action-TJCS6UEY.js} +41 -21
  81. package/chunks/{publish.action-T4J4DRXR.js → publish.action-T24VHRMR.js} +29 -24
  82. package/chunks/query-WKATAJJ6.js +129 -0
  83. package/chunks/scripts-VIBLGKYG.js +102 -0
  84. package/chunks/{update.action-3OVS3HWC.js → update.action-OGYNBXRU.js} +24 -19
  85. package/chunks/{update.action-MY7QPSSU.js → update.action-VOE6PH5F.js} +24 -19
  86. package/docs.html +1363 -320
  87. package/index.js +417 -174
  88. package/package.json +14 -13
  89. package/skills/scalar-cli/SKILL.md +13 -1
  90. package/template.md +157 -15
  91. package/chunks/action-JAHFRYWZ.js +0 -423
  92. package/chunks/action-N7BA5I3E.js +0 -229
  93. package/chunks/chunk-CWCETP6H.js +0 -610
  94. package/chunks/chunk-K74E42RV.js +0 -7311
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "engines": {
6
6
  "node": ">=24"
7
7
  },
8
- "version": "2.7.1",
8
+ "version": "2.10.0",
9
9
  "keywords": [
10
10
  "scalar",
11
11
  "openapi",
@@ -22,18 +22,18 @@
22
22
  "@clack/prompts": "0.7.0",
23
23
  "@hono/node-server": "2.1.1",
24
24
  "@quobix/vacuum": "0.30.1",
25
- "@scalar/asyncapi-upgrader": "0.1.13",
26
- "@scalar/asyncapi-validator": "0.1.6",
27
- "@scalar/json-magic": "0.15.2",
28
- "@scalar/mock-server": "0.17.0",
29
- "@scalar/openapi-parser": "0.29.7",
30
- "@scalar/openapi-to-markdown": "1.3.0",
31
- "@scalar/openapi-upgrader": "0.4.0",
32
- "@scalar/openapi-validator": "0.1.6",
33
- "@scalar/postman-to-openapi": "0.7.23",
34
- "@scalar/void-server": "2.5.13",
35
- "@scalar/workspace-store": "0.67.0",
25
+ "@scalar/asyncapi-upgrader": "0.1.15",
26
+ "@scalar/asyncapi-validator": "0.1.10",
27
+ "@scalar/json-magic": "0.15.5",
28
+ "@scalar/mock-server": "0.17.4",
29
+ "@scalar/openapi-to-markdown": "1.5.2",
30
+ "@scalar/openapi-upgrader": "0.4.2",
31
+ "@scalar/openapi-validator": "0.1.10",
32
+ "@scalar/postman-to-openapi": "0.7.25",
33
+ "@scalar/void-server": "2.5.15",
34
+ "@scalar/workspace-store": "0.68.1",
36
35
  "@stoplight/spectral-core": "1.22.0",
36
+ "@stoplight/spectral-parsers": "1.0.5",
37
37
  "@stoplight/spectral-ruleset-bundler": "1.7.0",
38
38
  "@stoplight/spectral-rulesets": "1.22.1",
39
39
  "ansis": "3.16.0",
@@ -50,6 +50,7 @@
50
50
  "semver": "7.6.3",
51
51
  "stdout-update": "4.0.1",
52
52
  "tar-fs": "3.1.2",
53
- "undici": "8.10.2"
53
+ "undici": "8.10.2",
54
+ "yaml": "2.8.3"
54
55
  }
55
56
  }
@@ -5,7 +5,7 @@ description: "Operate the Scalar CLI (`scalar`, or `npx @scalar/cli`) to validat
5
5
 
6
6
  # Scalar CLI
7
7
 
8
- CLI to work with your OpenAPI files (`@scalar/cli` 2.7.1).
8
+ CLI to work with your OpenAPI files (`@scalar/cli` 2.10.0).
9
9
 
10
10
  ## Operating notes
11
11
 
@@ -28,9 +28,17 @@ Run `scalar context` for the arguments, options, defaults, and choices of each c
28
28
  - `scalar readme generate [options]`: Self generate documentation for the cli
29
29
  - `scalar upgrade [options]`: Upgrade current version of your cli
30
30
  - `scalar context [options]`: Print every command, argument, and option as JSON for AI agents
31
+ - `scalar completion [options] <shell>`: Generate shell completion definitions
31
32
  - `scalar auth login [options]`: Login to scalar
32
33
  - `scalar auth whoami [options]`: Display the current user
33
34
  - `scalar auth logout [options]`: Logout from scalar
35
+ - `scalar access-group list [options]`: List access groups for the current team
36
+ - `scalar access-group create [options] <slug>`: Create an access group (Pro or above)
37
+ - `scalar access-group get [options] <slug>`: Get an access group and its allowlists
38
+ - `scalar access-group update [options] <slug>`: Update access group metadata
39
+ - `scalar access-group delete [options] <slug>`: Delete an access group and remove its project assignments
40
+ - `scalar access-group domain add [options] <slug> <domain>`: Add an exact email domain to an access group
41
+ - `scalar access-group domain remove [options] <slug> <domain>`: Remove an exact email domain from an access group
34
42
  - `scalar document bundle [options] [file|url]`: Bundle an OpenAPI document by resolving all references and external dependencies
35
43
  - `scalar document split [options] [file|url]`: Split OpenAPI or AsyncAPI documents into small chunks
36
44
  - `scalar document join [options] <files...>`: Merge multiple OpenAPI or AsyncAPI documents into a single unified document
@@ -44,6 +52,8 @@ Run `scalar context` for the arguments, options, defaults, and choices of each c
44
52
  - `scalar document void [options]`: Boot a server to mirror HTTP requests
45
53
  - `scalar document lint [options] [file|url]`: Lint your OpenAPI or AsyncAPI file using spectral rules
46
54
  - `scalar document upgrade [options] [file|url]`: Upgrade an OpenAPI or AsyncAPI document to version 3.1
55
+ - `scalar project list [options]`: List projects and their slugs for the current team.
56
+ - `scalar project get [options] <slug>`: Get project details for the current team.
47
57
  - `scalar project init [options]`: Create a new Scalar Docs project.
48
58
  - `scalar project check-config [options] [file]`: Check a Scalar Configuration file
49
59
  - `scalar project create [options]`: Create a new project that is not linked to a github project.
@@ -58,8 +68,10 @@ Run `scalar context` for the arguments, options, defaults, and choices of each c
58
68
  - `scalar registry list [options]`: List all registry APIs for a team namespace
59
69
  - `scalar registry get [options] [namespace] [slug]`: Get a document version from scalar registry
60
70
  - `scalar team list [options]`: List all teams current user is part of
71
+ - `scalar team get [options]`: Get the current team and its namespaces
61
72
  - `scalar team set [options]`: Set current active team for the user
62
73
  - `scalar sdk list [options]`: List all SDKs for a team namespace
74
+ - `scalar sdk get [options]`: Inspect SDK metadata, API source, versions, and build status
63
75
  - `scalar sdk create [options]`: Create a new SDK. The SDK is created in the namespace of the API it is built from.
64
76
  - `scalar sdk update [options]`: Update SDK metadata.
65
77
  - `scalar sdk delete [options]`: Delete an SDK.
package/template.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
  <COMMANDS>
@@ -132,6 +211,36 @@ cp -r "$(dirname "$(readlink "$(command -v scalar)")")/app/skills/scalar-cli" .c
132
211
 
133
212
  With the standalone CLI on Windows, the skill is in `%LOCALAPPDATA%\Scalar\current\app\skills\scalar-cli`.
134
213
 
214
+ ## Inspect SDKs
215
+
216
+ Use your current team login to inspect an SDK by slug. The namespace defaults to the team's first namespace.
217
+
218
+ ```bash
219
+ scalar sdk get --slug widgets --namespace acme
220
+ scalar sdk get --slug widgets --namespace acme --json
221
+ scalar sdk list --namespace acme --json
222
+ ```
223
+
224
+ 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.
225
+
226
+ ## Registry metadata for scripts
227
+
228
+ Use `scalar registry list --json` to write a JSON array to stdout. Without
229
+ `--namespace`, the command uses the first namespace of your current team, just
230
+ like the default table output. You must be logged in; errors go to stderr and
231
+ exit with a nonzero status.
232
+
233
+ ```bash
234
+ scalar registry list --namespace scalar --json > registry-apis.json
235
+ scalar registry get scalar demo-api --version 1.2.3 > openapi.json
236
+ ```
237
+
238
+ Each array entry contains `namespace` and `slug` (the coordinates accepted by
239
+ `registry get`), `title` (a string, which may be empty), `version` (the current
240
+ version served by default), and `isPrivate` (a boolean). JSON output includes
241
+ only these metadata fields, without document content or credentials. An empty
242
+ namespace returns `[]`. Omit `--json` for the human-readable table.
243
+
135
244
  ## GitHub Actions
136
245
 
137
246
  To validate your OpenAPI file in GitHub Actions, add this workflow:
@@ -163,30 +272,63 @@ jobs:
163
272
  run: npx @scalar/cli document validate ./my-openapi-file.yaml
164
273
  ```
165
274
 
166
- ## Development
275
+ ## CI lint reports and baselines
167
276
 
168
- Set up the development environment:
277
+ Lint reports support CI annotations, test-report viewers, and readable reviews:
169
278
 
170
- ```bash
171
- pnpm install
172
- pnpm @scalar/cli --version
279
+ ```sh
280
+ scalar document lint openapi.yaml --format codeframe
281
+ scalar document lint openapi.yaml --format markdown --output lint-results.md
282
+ scalar document lint openapi.yaml --format summary
283
+ scalar document lint openapi.yaml --format github-actions
284
+ scalar document lint openapi.yaml --format json --output lint-results.json
285
+ scalar document lint openapi.yaml --format junit --output lint-results.xml
173
286
  ```
174
287
 
175
- To symlink the package and use it globally on your machine:
288
+ 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.
176
289
 
177
- ```bash
178
- pnpm cli:link
179
- scalar --version
290
+ `--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.
291
+
292
+ 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:
293
+
294
+ ```sh
295
+ scalar document lint openapi.yaml --format json > lint-results.json
296
+ scalar document lint openapi.yaml --format json --output lint-results.json
297
+ ```
298
+
299
+ 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.
300
+
301
+ 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.
302
+
303
+ 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.
304
+
305
+ 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.
306
+
307
+ To adopt linting with existing findings:
308
+
309
+ ```sh
310
+ scalar document lint openapi.yaml --generate-ignore-file
311
+ scalar document lint openapi.yaml --format github-actions
180
312
  ```
181
313
 
182
- ### Docs preview from a local build
314
+ 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`.
315
+
316
+ 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.
317
+
318
+ The YAML mapping uses Redocly's source → rule → JSON-pointer structure:
319
+
320
+ ```yaml
321
+ openapi.yaml:
322
+ info-description:
323
+ - '#/info'
324
+ ```
183
325
 
184
- `scalar project preview` runs the docs in a preview server that the CLI downloads to `~/.scalar/isolate` on first use. Every CLI release publishes a matching archive to the CDN, so a released CLI always finds its own. A build from source has no archive until its version ships: the CLI then falls back to the newest published release with the same major version and says which one it used, and otherwise reports that the version is missing. To pin a specific published version instead, set `SSG_DOCS_ISOLATE_VERSION` to the version of a released CLI (`https://cdn.scalar.com/isolates/latest.json` names the newest one).
326
+ 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.
185
327
 
186
- ## Community
328
+ 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.
187
329
 
188
- We are API nerds. You too? Let’s chat on Discord: <https://discord.gg/scalar>
330
+ 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.
189
331
 
190
- ## License
332
+ ### Schema metadata
191
333
 
192
- The source code in this repository is licensed under [MIT](https://github.com/scalar/scalar/blob/main/LICENSE).
334
+ 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.