@scalar/cli 2.10.0 → 2.11.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 (99) hide show
  1. package/README.md +82 -1290
  2. package/chunks/{action-YSVTZVKV.js → action-25QMCP5G.js} +37 -26
  3. package/chunks/{action-X7BA7PQQ.js → action-2VF6LODL.js} +20 -18
  4. package/chunks/{action-5N3P43MD.js → action-5I4XDPPG.js} +16 -15
  5. package/chunks/action-6M5PTDF6.js +100 -0
  6. package/chunks/{action-PAM2EZ22.js → action-73ELLN3T.js} +8 -7
  7. package/chunks/{action-XOADBXSX.js → action-7H3AWCHX.js} +17 -16
  8. package/chunks/{action-KDUFU7TZ.js → action-BRSLSOE5.js} +19 -16
  9. package/chunks/{action-7XOHYWYM.js → action-CQQCKSNS.js} +13 -15
  10. package/chunks/action-D5QWDNQ2.js +65 -0
  11. package/chunks/{action-5RL4NWUZ.js → action-DQDHBOLJ.js} +33 -30
  12. package/chunks/{action-DKDRAIKV.js → action-EYPYQQVM.js} +13 -15
  13. package/chunks/{action-ZFI77WA5.js → action-FMA5ECUA.js} +10 -10
  14. package/chunks/{action-DTEO4YNX.js → action-GXDJLF2G.js} +13 -11
  15. package/chunks/{action-657A4K2D.js → action-HUICEXJZ.js} +26 -23
  16. package/chunks/action-IH6G77C5.js +38 -0
  17. package/chunks/{action-H3RTILLM.js → action-IIQMZVRJ.js} +1 -1
  18. package/chunks/action-IQM54ITT.js +164 -0
  19. package/chunks/{action-EAUTQ77U.js → action-J5TO3UJW.js} +26 -24
  20. package/chunks/{action-UUL6SWV4.js → action-KC3ZCNDR.js} +12 -14
  21. package/chunks/{action-HT42NUUX.js → action-L7TMS3Q3.js} +40 -38
  22. package/chunks/{action-GWYYTUTM.js → action-LAAHRDSR.js} +5 -5
  23. package/chunks/{action-5LF4XYHX.js → action-LR75GHBA.js} +12 -12
  24. package/chunks/{action-PPTFYZWD.js → action-MJMLQFLT.js} +12 -12
  25. package/chunks/action-NHU4CUKT.js +130 -0
  26. package/chunks/{action-4GZI2M5B.js → action-NKTFNFU7.js} +19 -17
  27. package/chunks/{action-CB55NWAU.js → action-NMW5WPD2.js} +9 -9
  28. package/chunks/{action-GFLRD7LO.js → action-OTPXODUE.js} +8 -8
  29. package/chunks/{action-R4PGILN4.js → action-RPCDNGCI.js} +47 -36
  30. package/chunks/{action-TOBU74JH.js → action-RQCXSJPZ.js} +51 -27
  31. package/chunks/{action-JEYDBB3P.js → action-SOYSVG67.js} +15 -15
  32. package/chunks/action-Y7EBKCUU.js +16 -0
  33. package/chunks/{action-XLE37MZL.js → action-YN4TE7TG.js} +23 -22
  34. package/chunks/{action-CABLS46Q.js → action-ZGNVWTHZ.js} +11 -11
  35. package/chunks/{action-4W5GUGEG.js → action-ZKKRPLDK.js} +20 -19
  36. package/chunks/{action-ZKA3RR3S.js → action-ZUZL7R3H.js} +18 -17
  37. package/chunks/{actions-3SAMH7A5.js → actions-S6K76HCW.js} +23 -20
  38. package/chunks/{agent-2ESZI7NO.js → agent-IRNEV4K5.js} +44 -9
  39. package/chunks/{asyncapi-4HGVM3PR.js → asyncapi-WQPIQMEZ.js} +13 -12
  40. package/chunks/{build.action-VBGFGACM.js → build.action-CLBVKFWD.js} +28 -26
  41. package/chunks/chunk-25XERWCE.js +1058 -0
  42. package/chunks/{chunk-35Z7VTJT.js → chunk-3RIUDHLG.js} +52 -38
  43. package/chunks/{chunk-ZYBLQ5CT.js → chunk-3TFOA64C.js} +9 -4
  44. package/chunks/{chunk-CWVYOXXM.js → chunk-4JKXZ5CF.js} +11 -7
  45. package/chunks/{chunk-XAGJJNQW.js → chunk-5L7V7RCH.js} +10 -10
  46. package/chunks/{chunk-KZNRQVMY.js → chunk-ALYM4ZB2.js} +1 -1
  47. package/chunks/chunk-AVZFSWPD.js +37 -0
  48. package/chunks/{chunk-GYRQPDTK.js → chunk-BQYVSPAI.js} +14 -2
  49. package/chunks/{chunk-UDBSV3CK.js → chunk-CSSTCHHF.js} +6083 -4167
  50. package/chunks/{chunk-ZGNDXPLU.js → chunk-DQD2753S.js} +3 -3
  51. package/chunks/{action-F2ZJNURT.js → chunk-EBNFCIKS.js} +7 -10
  52. package/chunks/{chunk-ATNTXKMS.js → chunk-F3OPMYME.js} +118 -38
  53. package/chunks/{chunk-KHF2QXBG.js → chunk-FG5AOTDN.js} +1433 -641
  54. package/chunks/{chunk-K2HIB5BA.js → chunk-GKCVATQJ.js} +3 -3
  55. package/chunks/{chunk-BIMLCGKS.js → chunk-GMHIK5K2.js} +1 -1
  56. package/chunks/{chunk-5SMP756H.js → chunk-GYR5E6RB.js} +2 -2
  57. package/chunks/{chunk-MC4EMNOR.js → chunk-HZN6IIPZ.js} +7 -6
  58. package/chunks/{chunk-VVRUSQCY.js → chunk-I57ID5K7.js} +13 -0
  59. package/chunks/{chunk-VYFGRLVQ.js → chunk-KOD2HX5I.js} +1 -1
  60. package/chunks/{chunk-ZKJPLWRJ.js → chunk-LOLVJNI5.js} +4 -4
  61. package/chunks/{chunk-GLWTVLKM.js → chunk-MN2AFJXM.js} +9 -2
  62. package/chunks/{chunk-WB6PWTMU.js → chunk-N5CJ5MTY.js} +1 -1
  63. package/chunks/{chunk-JXGF5EHC.js → chunk-NWJ37GI2.js} +23 -13
  64. package/chunks/{chunk-3ZJYGGAA.js → chunk-ORCUZITN.js} +1 -1
  65. package/chunks/{chunk-H467HDVV.js → chunk-QMLRYD76.js} +1 -1
  66. package/chunks/{chunk-43WALAW3.js → chunk-SEURG74P.js} +64 -115
  67. package/chunks/{chunk-G4HRW2FZ.js → chunk-SOV4POMS.js} +366 -253
  68. package/chunks/chunk-T34TL6KL.js +222 -0
  69. package/chunks/{chunk-WDIWLXLV.js → chunk-U6VE6JOS.js} +3 -3
  70. package/chunks/{chunk-MMWSCTDB.js → chunk-UFSFY7Z4.js} +19 -19
  71. package/chunks/{chunk-WIEXQUTD.js → chunk-ULRJZXMS.js} +1 -1
  72. package/chunks/{chunk-DHZW7Q7U.js → chunk-US54KYOJ.js} +2 -4
  73. package/chunks/{chunk-36LXIJIZ.js → chunk-V6LUKXBV.js} +1 -16
  74. package/chunks/{chunk-6M7TL2G2.js → chunk-VRZSDUZK.js} +45 -5
  75. package/chunks/chunk-VUXPDHTQ.js +22 -0
  76. package/chunks/chunk-XP5UM7SF.js +21 -0
  77. package/chunks/{chunk-IPZP3VRA.js → chunk-Y6XGC4K5.js} +5 -21
  78. package/chunks/{create.action-DBNIS665.js → create.action-ITEOQ644.js} +34 -32
  79. package/chunks/{delete.action-K7BLK7DK.js → delete.action-77MFPLUN.js} +29 -27
  80. package/chunks/{delete.action-GBOZC45K.js → delete.action-C6VX4S5Q.js} +30 -28
  81. package/chunks/{get.action-N3JOY3OU.js → get.action-3BP4FHZC.js} +16 -15
  82. package/chunks/{get.action-QHKMYZBK.js → get.action-LNBOWUVE.js} +24 -20
  83. package/chunks/{list.action-6SSO3JVN.js → list.action-6CRFQPJT.js} +39 -29
  84. package/chunks/{list.action-TJCS6UEY.js → list.action-KR5YIDR4.js} +37 -26
  85. package/chunks/{publish.action-T24VHRMR.js → publish.action-YBORRPBM.js} +45 -43
  86. package/chunks/{scripts-VIBLGKYG.js → scripts-6CI6U32J.js} +1 -1
  87. package/chunks/{update.action-VOE6PH5F.js → update.action-O7TSXDGV.js} +29 -27
  88. package/chunks/{update.action-OGYNBXRU.js → update.action-QZI7M2MV.js} +30 -28
  89. package/index.js +283 -278
  90. package/package.json +2 -2
  91. package/skills/scalar-cli/SKILL.md +49 -49
  92. package/template.md +66 -253
  93. package/chunks/action-FBRY5JKU.js +0 -37
  94. package/chunks/action-LYCNT3KA.js +0 -73
  95. package/chunks/action-OJ2NK25F.js +0 -121
  96. package/chunks/action-U2L5DCFG.js +0 -91
  97. package/chunks/chunk-MNNGUUKJ.js +0 -405
  98. package/chunks/chunk-ZGVZU6L2.js +0 -422
  99. package/docs.html +0 -6977
package/README.md CHANGED
@@ -2,1367 +2,159 @@
2
2
 
3
3
  [![Version](https://img.shields.io/npm/v/%40scalar/cli)](https://www.npmjs.com/package/@scalar/cli)
4
4
  [![Downloads](https://img.shields.io/npm/dm/%40scalar/cli)](https://www.npmjs.com/package/@scalar/cli)
5
- [![License](https://img.shields.io/npm/l/%40scalar%2Fapi-reference)](https://www.npmjs.com/package/@scalar/cli)
6
5
  [![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)
7
6
 
8
- Command-line interface to work with OpenAPI files
7
+ Validate, lint, bundle, mock, and preview OpenAPI and AsyncAPI documents from your terminal, then publish them to [Scalar](https://scalar.com).
9
8
 
10
- ## Features
11
-
12
- - Format & validate OpenAPI files
13
- - Upload your OpenAPI files to Scalar
14
- - Get a fully mocked API for testing purposes
15
- - Preview your API reference
16
- - Bundle multiple OpenAPI files
17
-
18
- ## Projects
19
-
20
- Discover project slugs and inspect project details without opening the Dashboard:
9
+ ![The Scalar CLI validating, linting, bundling, and serving an OpenAPI document](https://raw.githubusercontent.com/scalar/scalar/main/documentation/assets/cli/scalar-cli.webp)
21
10
 
22
11
  ```bash
23
- scalar auth login
24
- scalar project list
25
- scalar project get my-docs
26
- scalar project deployments list --slug my-docs
12
+ npx @scalar/cli document validate openapi.yaml
27
13
  ```
28
14
 
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.
15
+ [Documentation](https://scalar.com/tools/cli/getting-started) · [Command reference](https://scalar.com/tools/cli/commands) · [CI and scripting](https://scalar.com/tools/cli/ci-and-scripting) · [Discord](https://discord.gg/scalar)
30
16
 
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.
17
+ ## Common tasks
32
18
 
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.
19
+ Every example works with `npx @scalar/cli` in place of `scalar` if you have not installed the CLI.
34
20
 
35
- ## Documentation
36
-
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)
38
-
39
- ## Quickstart
21
+ ### Validate and lint an API description
40
22
 
41
23
  ```bash
42
- npx @scalar/cli help
24
+ scalar document validate openapi.yaml
25
+ scalar document lint openapi.yaml
26
+ scalar document lint openapi.yaml --rule .spectral.yaml
43
27
  ```
44
28
 
45
- ## Installation
46
-
47
- ### Standalone CLI (no Node.js required)
48
-
49
- Install the latest stable release without Node.js, npm, or administrator access.
29
+ `validate` checks the document against the OpenAPI or AsyncAPI specification. `lint` applies Spectral rules and fails only on errors. [Lint reports and baselines →](https://scalar.com/tools/cli/ci-and-scripting#lint-reports)
50
30
 
51
- macOS and Linux (Bash):
31
+ ### Bundle split files into one
52
32
 
53
33
  ```bash
54
- curl -fsSL https://cdn.scalar.com/cli/install.sh | bash
34
+ scalar document bundle openapi.yaml --output openapi.bundled.yaml
35
+ scalar document bundle openapi.yaml --output openapi.bundled.yaml --treeShake
55
36
  ```
56
37
 
57
- Windows (PowerShell):
58
-
59
- ```powershell
60
- irm https://cdn.scalar.com/cli/install.ps1 | iex
61
- ```
62
-
63
- The installers choose the archive for your platform and verify its SHA-256 checksum before installing. macOS and Linux support x64 and ARM64; Linux requires glibc. Windows supports x64 and requires `tar.exe`, included in Windows 10 version 1803 and later.
64
-
65
- On macOS and Linux, follow the printed PATH instructions if needed. On Windows, open a new terminal after installation. Then run `scalar --help`. Re-run the installer to upgrade.
38
+ Pulls every external `$ref` into a single file. `--treeShake` drops components nothing uses. The input can be a URL.
66
39
 
67
- See the [portable CLI guide](https://github.com/scalar/scalar-org/blob/main/projects/cli/portable/README.md) for installation locations, version selection, custom directories, and direct downloads. You can download and inspect either script before running it.
68
-
69
- ### npm
70
-
71
- If you already use Node.js, install the CLI with npm:
40
+ ### Preview the API reference
72
41
 
73
42
  ```bash
74
- npm -g install @scalar/cli
43
+ scalar document serve openapi.yaml --watch
75
44
  ```
76
45
 
77
- Otherwise just prefix all commands with `npx @scalar/cli` instead of `scalar`. That’s fine, too.
78
-
79
- ### Conflict: EXIST: file already exists
80
-
81
- There’s another `scalar` CLI, which is bundled with `git`. If you run into naming conflicts, but never use the other CLI anyway, you can replace it like this:
46
+ Serves an interactive API reference that reloads as you edit. Pass `--config reference.json` for [API Reference options](https://scalar.com/products/api-references/configuration).
82
47
 
83
- ```bash
84
- npm -g --force install @scalar/cli
85
- ```
86
-
87
- Or, if you want to keep using the other `scalar` CLI, you can just stick to `npx` (or `pnpm dlx`):
48
+ ### Mock the API
88
49
 
89
50
  ```bash
90
- # Execute without installation (npm)
91
- npx @scalar/cli help
92
-
93
- # Execute without installation (pnpm)
94
- pnpm dlx @scalar/cli help
51
+ scalar document mock openapi.yaml --watch
95
52
  ```
96
53
 
97
- ## Shell completion
54
+ Starts a mock server that answers with the examples and schemas in your document, so you can try requests before the API exists.
98
55
 
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
56
+ ### Upgrade and convert
102
57
 
103
58
  ```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
-
146
- ## API Reference configuration
147
-
148
- Pass API Reference options as a JSON object:
149
-
150
- ```sh
151
- scalar document serve openapi.yaml --config ./reference.config.json
152
- ```
153
-
154
- ```json
155
- {
156
- "orderRequiredPropertiesFirst": false,
157
- "theme": "purple"
158
- }
59
+ scalar document upgrade swagger.json --output openapi.json
60
+ scalar document convert postman-collection.json --output openapi.json
159
61
  ```
160
62
 
161
- The configuration path is relative to the current working directory. Configuration
162
- is loaded at startup; restart the command after changing it. `--watch` continues
163
- to watch the API document. Options requiring JavaScript functions are not supported
164
- in a JSON file.
165
-
166
- ## Authentication in automation
167
-
168
- Use `scalar auth login --token <personal-token>` to authenticate without a browser.
169
- Alternatively, set `SCALAR_API_KEY`. When both are provided, `SCALAR_API_KEY` takes
170
- precedence over `--token`. Unset it to use a different explicit token.
171
-
172
- Supply required options in automation instead of relying on interactive prompts.
173
- For example, pass `--output` for document transformations.
63
+ Upgrades Swagger 2.0 and OpenAPI 3.0 to OpenAPI 3.1, and converts Postman collections to OpenAPI.
174
64
 
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:
65
+ ### Publish to Scalar
180
66
 
181
67
  ```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
-
188
- ## Commands
189
-
190
- ```
191
- Usage: scalar [options] [command]
192
-
193
- CLI to work with your OpenAPI files
194
-
195
- Options:
196
- -v, --version output the version number
197
- -h, --help display help for command
198
-
199
- Commands:
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
213
- ```
214
-
215
- ### readme
216
- ```
217
- Usage: scalar readme [options] [command]
218
-
219
- Open documentation for the CLI
220
-
221
- Options:
222
- -h, --help display help for command
223
-
224
- Commands:
225
- generate [options] Self generate documentation for the cli
226
- ```
227
-
228
- #### generate
229
- ```
230
- Usage: scalar readme generate [options]
231
-
232
- Self generate documentation for the cli
233
-
234
- Options:
235
- -o, --output [file] Path where the documentation file will be written
236
- -h, --help display help for command
237
- ```
238
-
239
- ### upgrade
240
- ```
241
- Usage: scalar upgrade [options]
242
-
243
- Upgrade current version of your cli
244
-
245
- Options:
246
- -h, --help display help for command
247
- ```
248
-
249
- ### context
250
- ```
251
- Usage: scalar context [options]
252
-
253
- Print every command, argument, and option as JSON for AI agents
254
-
255
- Options:
256
- -h, --help display help for command
257
- ```
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
-
272
- ### auth
273
- ```
274
- Usage: scalar auth [options] [command]
275
-
276
- Manage authorization on scalar platform
277
-
278
- Options:
279
- -h, --help display help for command
280
-
281
- Commands:
282
- login [options] Login to scalar
283
- whoami Display the current user
284
- logout Logout from scalar
285
- help [command] display help for command
286
- ```
287
-
288
- #### login
289
- ```
290
- Usage: scalar auth login [options]
291
-
292
- Login to scalar
293
-
294
- Options:
295
- --token <token> Personal token
296
- -h, --help display help for command
297
- ```
298
-
299
- #### whoami
300
- ```
301
- Usage: scalar auth whoami [options]
302
-
303
- Display the current user
304
-
305
- Options:
306
- -h, --help display help for command
307
- ```
308
-
309
- #### logout
310
- ```
311
- Usage: scalar auth logout [options]
312
-
313
- Logout from scalar
314
-
315
- Options:
316
- -h, --help display help for command
317
- ```
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
-
457
- ### document
458
- ```
459
- Usage: scalar document [options] [command]
460
-
461
- Manage local openapi file
462
-
463
- Options:
464
- -h, --help display help for command
465
-
466
- Commands:
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
473
- format [options] [file|url] Format an OpenAPI or AsyncAPI file
474
- convert [options] [file|url] Convert a Postman collection to an OpenAPI
475
- document
476
- markdown [options] [file|url] Generate Markdown from an OpenAPI file
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
481
- share [options] [file] Share an OpenAPI or AsyncAPI file
482
- validate [file|url] Validate an OpenAPI or AsyncAPI file
483
- void [options] Boot a server to mirror HTTP requests
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
488
- help [command] display help for command
489
- ```
490
-
491
- #### bundle
492
- ```
493
- Usage: scalar document bundle [options] [file|url]
494
-
495
- Bundle an OpenAPI document by resolving all references and external dependencies
496
-
497
- Arguments:
498
- file|url Path to OpenAPI file or URL to bundle
499
-
500
- Options:
501
- -o, --output <file> Path to save the bundled output file
502
- --treeShake Remove unused components from the bundled output
503
- --urlMap Generate a map of resolved URLs in the bundled output
504
- --fetchLimit <limit> Maximum number of URLs to fetch during bundling at the
505
- same time
506
- -h, --help display help for command
507
- ```
508
-
509
- #### split
510
- ```
511
- Usage: scalar document split [options] [file|url]
512
-
513
- Split OpenAPI or AsyncAPI documents into small chunks
514
-
515
- Arguments:
516
- file|url Path to OpenAPI or AsyncAPI file or URL to split
517
-
518
- Options:
519
- -o, --output <path> Path to save the chunks
520
- -h, --help display help for command
521
- ```
522
-
523
- #### join
524
- ```
525
- Usage: scalar document join [options] <files...>
526
-
527
- Merge multiple OpenAPI or AsyncAPI documents into a single unified document
528
-
529
- Arguments:
530
- files Paths to the OpenAPI or AsyncAPI files to merge
531
-
532
- Options:
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
536
- ```
537
-
538
- #### format
539
- ```
540
- Usage: scalar document format [options] [file|url]
541
-
542
- Format an OpenAPI or AsyncAPI file
543
-
544
- Arguments:
545
- file|url File or URL to format
546
-
547
- Options:
548
- -o, --output <file> Output file
549
- -h, --help display help for command
550
- ```
551
-
552
- #### convert
553
- ```
554
- Usage: scalar document convert [options] [file|url]
555
-
556
- Convert a Postman collection to an OpenAPI document
557
-
558
- Arguments:
559
- file|url Postman collection file path or URL to convert
560
-
561
- Options:
562
- -o, --output <file> Output file (defaults to stdout)
563
- --merge-operations Merge operations with shared path+method combinations
564
- -h, --help display help for command
565
- ```
566
-
567
- #### markdown
568
- ```
569
- Usage: scalar document markdown [options] [file|url]
570
-
571
- Generate Markdown from an OpenAPI file
572
-
573
- Arguments:
574
- file|url OpenAPI file path or URL to convert
575
-
576
- Options:
577
- -o, --output <file> Output file (defaults to stdout)
578
- -h, --help display help for command
579
- ```
580
-
581
- #### mock
582
- ```
583
- Usage: scalar document mock [options] [file|url]
584
-
585
- Mock an OpenAPI API or AsyncAPI WebSocket and SSE channels
586
-
587
- Arguments:
588
- file|url OpenAPI or AsyncAPI file or URL to mock
589
-
590
- Options:
591
- -w, --watch watch the file for changes
592
- -o, --once run the server only once and exit after that
593
- -p, --port <port> set the HTTP port for the mock server
594
- -h, --help display help for command
595
- ```
596
-
597
- #### serve
598
- ```
599
- Usage: scalar document serve [options] [file|url]
600
-
601
- Serve an API Reference from an OpenAPI or AsyncAPI file
602
-
603
- Arguments:
604
- file|url OpenAPI or AsyncAPI file or URL to show the reference for
605
-
606
- Options:
607
- -c, --config <file> JSON file with API Reference configuration
608
- -w, --watch watch the file for changes
609
- -o, --once run the server only once and exit after that
610
- -p, --port <port> set the HTTP port for the API reference server
611
- -h, --help display help for command
612
- ```
613
-
614
- #### share
615
- ```
616
- Usage: scalar document share [options] [file]
617
-
618
- Share an OpenAPI or AsyncAPI file
619
-
620
- Arguments:
621
- file file to share
622
-
623
- Options:
624
- -t, --token <token> pass a token to update an existing sandbox
625
- -h, --help display help for command
626
- ```
627
-
628
- #### validate
629
- ```
630
- Usage: scalar document validate [options] [file|url]
631
-
632
- Validate an OpenAPI or AsyncAPI file
633
-
634
- Arguments:
635
- file|url File or URL to validate
636
-
637
- Options:
638
- -h, --help display help for command
639
- ```
640
-
641
- #### void
642
- ```
643
- Usage: scalar document void [options]
644
-
645
- Boot a server to mirror HTTP requests
646
-
647
- Options:
648
- -o, --once run the server only once and exit after that
649
- -p, --port <port> set the HTTP port for the mock server
650
- -h, --help display help for command
651
- ```
652
-
653
- #### lint
654
- ```
655
- Usage: scalar document lint [options] [file|url]
656
-
657
- Lint your OpenAPI or AsyncAPI file using spectral rules
658
-
659
- Arguments:
660
- file|url OpenAPI or AsyncAPI file path or url
661
-
662
- Options:
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
674
- ```
675
-
676
- #### upgrade
677
- ```
678
- Usage: scalar document upgrade [options] [file|url]
679
-
680
- Upgrade an OpenAPI or AsyncAPI document to version 3.1
681
-
682
- Arguments:
683
- file|url File or URL to upgrade
684
-
685
- Options:
686
- -o, --output <file> Path to save the upgraded output file
687
- -h, --help display help for command
688
- ```
689
-
690
- ### project
691
- ```
692
- Usage: scalar project [options] [command]
693
-
694
- Manage scalar project
695
-
696
- Options:
697
- -h, --help display help for command
698
-
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.
703
- init [options] Create a new Scalar Docs project.
704
- check-config [file] Check a Scalar Configuration file
705
- create [options] Create a new project that is not linked to a
706
- github project.
707
- preview [options] [config] Preview scalar guides
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.
712
- deployments Inspect a project deployment history.
713
- upgrade [config] Upgrade scalar project
714
- help [command] display help for command
715
- ```
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
-
742
- #### init
743
- ```
744
- Usage: scalar project init [options]
745
-
746
- Create a new Scalar Docs project.
747
-
748
- Options:
749
- -s, --subdomain [url] subdomain to publish on
750
- --force override existing configuration
751
- -h, --help display help for command
752
- ```
753
-
754
- #### check-config
755
- ```
756
- Usage: scalar project check-config [options] [file]
757
-
758
- Check a Scalar Configuration file
759
-
760
- Arguments:
761
- file File to check
762
-
763
- Options:
764
- -h, --help display help for command
765
- ```
766
-
767
- #### create
768
- ```
769
- Usage: scalar project create [options]
770
-
771
- Create a new project that is not linked to a github project.
772
-
773
- Options:
774
- -n, --name <name> name of your project
775
- -s, --slug <slug> project slug
776
- -h, --help display help for command
777
- ```
778
-
779
- #### preview
780
- ```
781
- Usage: scalar project preview [options] [config]
782
-
783
- Preview scalar guides
784
-
785
- Arguments:
786
- config Path to the Scalar configuration file (usually
787
- `scalar.config.json5` or `scalar.config.json`)
788
-
789
- Options:
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")
797
- -N, --no-open Do not open the browser automatically
798
- -h, --help display help for command
799
- ```
800
-
801
- #### publish
802
- ```
803
- Usage: scalar project publish [options]
804
-
805
- Publish new build for a github sync project that is not linked.
806
-
807
- Options:
808
- -s, --slug [slug] Project slug from scalar project list
809
- -c, --config [config] Your config file of the project
810
- -p, --preview Publish in preview mode
811
- -g, --github Publish from your linked remote GitHub repository
812
- -h, --help display help for command
813
- ```
814
-
815
- #### rollback
816
- ```
817
- Usage: scalar project rollback [options]
818
-
819
- Roll the live deployment back to a previously deployed build.
820
-
821
- Options:
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)
825
- -y, --yes Skip the confirmation prompt
826
- -h, --help display help for command
827
- ```
828
-
829
- #### deployments
830
- ```
831
- Usage: scalar project deployments [options] [command]
832
-
833
- Inspect a project deployment history.
834
-
835
- Options:
836
- -h, --help display help for command
837
-
838
- Commands:
839
- list [options] List the production deployment history for a project.
840
- help [command] display help for command
841
- ```
842
-
843
- ##### list
844
- ```
845
- Usage: scalar project deployments list [options]
846
-
847
- List the production deployment history for a project.
848
-
849
- Options:
850
- -s, --slug [slug] Project slug from scalar project list
851
- -h, --help display help for command
852
- ```
853
-
854
- #### upgrade
855
- ```
856
- Usage: scalar project upgrade [options] [config]
857
-
858
- Upgrade scalar project
859
-
860
- Arguments:
861
- config Path to the Scalar configuration file (usually
862
- `scalar.config.json5` or `scalar.config.json`)
863
-
864
- Options:
865
- -h, --help display help for command
866
- ```
867
-
868
- ### registry
869
- ```
870
- Usage: scalar registry [options] [command]
871
-
872
- Manage your scalar registry
873
-
874
- Options:
875
- -h, --help display help for command
876
-
877
- Commands:
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
882
- delete [namespace] [slug] Delete a document from scalar registry
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
887
- help [command] display help for command
888
- ```
889
-
890
- #### publish
891
- ```
892
- Usage: scalar registry publish [options] [file]
893
-
894
- Publish an OpenAPI document to the Scalar registry
895
-
896
- Arguments:
897
- file OpenAPI file to upload
898
-
899
- Options:
900
- --slug <slug> Slug identifier for the registry entry. Defaults to
901
- title.
902
- --namespace <namespace> Scalar team namespace
903
- --version <version> API version (e.g. 0.1.0)
904
- --private Make API private (default: false)
905
- --no-current Do not set as the current version
906
- --force Force override an existing version (default: false)
907
- --bundle Bundle all external references before uploading
908
- --treeShake Remove unused components from the bundled document
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
913
- -h, --help display help for command
914
- ```
915
-
916
- #### update
917
- ```
918
- Usage: scalar registry update [options] [namespace] [slug]
919
-
920
- Update document metadata on scalar registry
921
-
922
- Arguments:
923
- namespace namespace of document you want to update
924
- slug slug of document you want to update
925
-
926
- Options:
927
- --title <title> Document title
928
- --description <description> Document description
929
- -h, --help display help for command
930
- ```
931
-
932
- #### delete
933
- ```
934
- Usage: scalar registry delete [options] [namespace] [slug]
935
-
936
- Delete a document from scalar registry
937
-
938
- Arguments:
939
- namespace Team namespace
940
- slug Managed doc slug
941
-
942
- Options:
943
- -h, --help display help for command
944
- ```
945
-
946
- #### list
947
- ```
948
- Usage: scalar registry list [options]
949
-
950
- List all registry APIs for a team namespace
951
-
952
- Options:
953
- --namespace <namespace> Team namespace
954
- --json Output registry API metadata as JSON
955
- -h, --help display help for command
956
- ```
957
-
958
- #### get
959
- ```
960
- Usage: scalar registry get [options] [namespace] [slug]
961
-
962
- Get a document version from scalar registry
963
-
964
- Arguments:
965
- namespace Team namespace
966
- slug Managed doc slug
967
-
968
- Options:
969
- --version <version> Document version (defaults to latest)
970
- --format <format> Output format (json or yaml) (choices: "json", "yaml", default: "json")
971
- -o, --output <file> Output file (defaults to stdout)
972
- -h, --help display help for command
973
- ```
974
-
975
- ### team
976
- ```
977
- Usage: scalar team [options] [command]
978
-
979
- Manage user teams
980
-
981
- Options:
982
- -h, --help display help for command
983
-
984
- Commands:
985
- list [options] List all teams current user is part of
986
- get [options] Get the current team and its namespaces
987
- set [options] Set current active team for the user
988
- help [command] display help for command
989
- ```
990
-
991
- #### list
992
- ```
993
- Usage: scalar team list [options]
994
-
995
- List all teams current user is part of
996
-
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
1010
- -h, --help display help for command
1011
- ```
1012
-
1013
- #### set
1014
- ```
1015
- Usage: scalar team set [options]
1016
-
1017
- Set current active team for the user
1018
-
1019
- Options:
1020
- --team <team> Team uid
1021
- -h, --help display help for command
1022
- ```
1023
-
1024
- ### sdk
1025
- ```
1026
- Usage: scalar sdk [options] [command]
1027
-
1028
- Manage your Scalar SDKs (Enterprise Only)
1029
-
1030
- Options:
1031
- -h, --help display help for command
1032
-
1033
- Commands:
1034
- list [options] List all SDKs for a team namespace
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.
1038
- update [options] Update SDK metadata.
1039
- delete [options] Delete an SDK.
1040
- build [options] Build an SDK.
1041
- help [command] display help for command
1042
- ```
1043
-
1044
- #### list
1045
- ```
1046
- Usage: scalar sdk list [options]
1047
-
1048
- List all SDKs for a team namespace
1049
-
1050
- Options:
1051
- --json Output structured SDK metadata as JSON
1052
- --namespace <namespace> Team namespace
1053
- -h, --help display help for command
1054
- ```
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
-
1069
- #### create
1070
- ```
1071
- Usage: scalar sdk create [options]
1072
-
1073
- Create a new SDK. The SDK is created in the namespace of the API it is built
1074
- from.
1075
-
1076
- Options:
1077
- -a, --api <api> Registry API slug
1078
- -n, --namespace <namespace> Team namespace to look the API up in
1079
- -l, --language <language> Language of your SDK (choices: "typescript",
1080
- "python", "cli", "csharp", "java", "ruby", "php",
1081
- "go", "rust", "kotlin", "swift", "cpp", "dart")
1082
- -h, --help display help for command
1083
- ```
1084
-
1085
- #### update
1086
- ```
1087
- Usage: scalar sdk update [options]
1088
-
1089
- Update SDK metadata.
1090
-
1091
- Options:
1092
- -s, --slug <slug> SDK slug
1093
- -n, --namespace <namespace> Team namespace
1094
- --title <title> Title
1095
- --isPrivate <isPrivate> Privacy (true/false or public/private) (choices: "true", "false", "public", "private")
1096
- -h, --help display help for command
1097
- ```
1098
-
1099
- #### delete
1100
- ```
1101
- Usage: scalar sdk delete [options]
1102
-
1103
- Delete an SDK.
1104
-
1105
- Options:
1106
- -s, --slug <slug> SDK slug
1107
- -n, --namespace <namespace> Team namespace
1108
- -h, --help display help for command
1109
- ```
1110
-
1111
- #### build
1112
- ```
1113
- Usage: scalar sdk build [options]
1114
-
1115
- Build an SDK.
1116
-
1117
- Options:
1118
- -s, --slug <slug> SDK slug
1119
- -n, --namespace <namespace> Team namespace
1120
- -h, --help display help for command
1121
- ```
1122
-
1123
- ### schema
1124
- ```
1125
- Usage: scalar schema [options] [command]
1126
-
1127
- Manage your Scalar schemas
1128
-
1129
- Options:
1130
- -h, --help display help for command
1131
-
1132
- Commands:
1133
- delete [options] Delete a schema.
1134
- update [options] Update schema metadata.
1135
- list [options] List all schemas for a team namespace
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
1140
- help [command] display help for command
1141
- ```
1142
-
1143
- #### delete
1144
- ```
1145
- Usage: scalar schema delete [options]
1146
-
1147
- Delete a schema.
1148
-
1149
- Options:
1150
- -s, --slug <slug> Schema slug
1151
- -n, --namespace <namespace> Team namespace
1152
- -h, --help display help for command
1153
- ```
1154
-
1155
- #### update
1156
- ```
1157
- Usage: scalar schema update [options]
1158
-
1159
- Update schema metadata.
1160
-
1161
- Options:
1162
- -s, --slug <slug> Schema slug
1163
- -n, --namespace <namespace> Team namespace
1164
- --title <title> Title
1165
- --description <description> Description
1166
- --isPrivate <isPrivate> Privacy (true/false or public/private) (choices: "true", "false", "public", "private")
1167
- -h, --help display help for command
1168
- ```
1169
-
1170
- #### list
1171
- ```
1172
- Usage: scalar schema list [options]
1173
-
1174
- List all schemas for a team namespace
1175
-
1176
- Options:
1177
- --namespace <namespace> Team namespace
1178
- --json Output schema metadata as JSON
1179
- -h, --help display help for command
68
+ scalar auth login
69
+ scalar registry publish openapi.yaml --namespace acme --slug my-api --version 1.0.0
70
+ scalar project preview
71
+ scalar project publish --slug my-docs
1180
72
  ```
1181
73
 
1182
- #### get
1183
- ```
1184
- Usage: scalar schema get [options] [namespace] [slug]
74
+ Push API descriptions to the [Scalar Registry](https://scalar.com/products/registry/getting-started), preview a Scalar Docs project locally, and publish it. In CI, run `scalar auth login --token <token>`, or set `SCALAR_API_KEY` and run `scalar auth login`.
1185
75
 
1186
- Get a schema document version from the Scalar registry
76
+ ## Install
1187
77
 
1188
- Arguments:
1189
- namespace Team namespace
1190
- slug Schema slug
78
+ Standalone binary, no Node.js required:
1191
79
 
1192
- Options:
1193
- --version <version> Schema version (defaults to latest)
1194
- --format <format> Output format (json or yaml) (choices: "json", "yaml", default: "json")
1195
- -o, --output <file> Output file (defaults to stdout)
1196
- -h, --help display help for command
80
+ ```bash
81
+ # macOS and Linux
82
+ curl -fsSL https://cdn.scalar.com/cli/install.sh | bash
1197
83
  ```
1198
84
 
1199
- #### publish
85
+ ```powershell
86
+ # Windows (PowerShell)
87
+ irm https://cdn.scalar.com/cli/install.ps1 | iex
1200
88
  ```
1201
- Usage: scalar schema publish [options] [file]
1202
89
 
1203
- Publish a shared schema to the Scalar registry
90
+ Or with npm:
1204
91
 
1205
- Arguments:
1206
- file OpenAPI file to upload
1207
-
1208
- Options:
1209
- --slug <slug> Slug identifier for the registry entry. Defaults to
1210
- title.
1211
- --title <title> Schema title
1212
- --namespace <namespace> Scalar team namespace
1213
- --version <version> API version (e.g. 0.1.0)
1214
- --private Make API private (default: false)
1215
- --force Force override an existing version (default: false)
1216
- --bundle Bundle all external references before uploading
1217
- --treeShake Remove unused components from the bundled document
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
1222
- -h, --help display help for command
92
+ ```bash
93
+ npm install --global @scalar/cli
1223
94
  ```
1224
95
 
96
+ Git ships an unrelated `scalar` executable. If it gets in the way, use npm's `scalar-cli` alias, or run `npm install --global --force @scalar/cli` to replace it. The [installation guide](https://scalar.com/tools/cli/getting-started#installation) covers upgrades and shell completion.
1225
97
 
1226
- ## AI agents
98
+ ## Use with AI agents
1227
99
 
1228
- `scalar context` prints the whole command tree as JSON: every command with its arguments, options, defaults, and choices, plus notes on running the CLI without prompts and what each exit code means. Point an agent at it instead of having it scrape `--help`:
100
+ `scalar context` prints every command, argument, option, default, and choice as JSON, plus notes on running without prompts. Point your agent at it instead of `--help`:
1229
101
 
1230
102
  ```bash
1231
103
  scalar context
1232
104
  ```
1233
105
 
1234
- The CLI also ships an [Agent Skill](https://agentskills.io) at `skills/scalar-cli/SKILL.md`, in the npm package and in the `app` directory of the standalone archives. Copy it into your agent's skills directory to teach the agent how to use the CLI:
106
+ The package also ships an [Agent Skill](https://agentskills.io) at `skills/scalar-cli/SKILL.md`. Copy it into your project:
1235
107
 
1236
108
  ```bash
1237
109
  mkdir -p .claude/skills
1238
-
1239
- # npm (global install)
1240
110
  cp -r "$(npm root -g)/@scalar/cli/skills/scalar-cli" .claude/skills/
1241
-
1242
- # Standalone CLI on macOS or Linux (the installer links `scalar` into its release directory)
1243
- cp -r "$(dirname "$(readlink "$(command -v scalar)")")/app/skills/scalar-cli" .claude/skills/
1244
111
  ```
1245
112
 
1246
- With the standalone CLI on Windows, the skill is in `%LOCALAPPDATA%\Scalar\current\app\skills\scalar-cli`.
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
-
1278
- ## GitHub Actions
1279
-
1280
- To validate your OpenAPI file in GitHub Actions, add this workflow:
113
+ ## Use in CI
1281
114
 
1282
115
  ```yml
1283
- # .github/workflows/validate-openapi-file.yml
1284
- name: Validate OpenAPI File
1285
-
1286
- on:
1287
- push:
1288
- branches:
1289
- - main
1290
- pull_request:
1291
- branches:
1292
- - main
116
+ # .github/workflows/openapi.yml
117
+ name: OpenAPI
118
+ on: [push, pull_request]
1293
119
 
1294
120
  jobs:
1295
- validate:
121
+ lint:
1296
122
  runs-on: ubuntu-latest
1297
-
1298
123
  steps:
1299
- - uses: actions/checkout@v4
1300
- - name: Use Node.js
1301
- uses: actions/setup-node@v4
124
+ - uses: actions/checkout@v6
125
+ - uses: actions/setup-node@v6
1302
126
  with:
1303
127
  node-version: 24
1304
- - name: Validate OpenAPI File
1305
- # Replace `./my-openapi-file.yaml` with the correct path and filename for your project.
1306
- run: npx @scalar/cli document validate ./my-openapi-file.yaml
128
+ - run: npx --yes @scalar/cli document lint openapi.yaml --format github-actions
1307
129
  ```
1308
130
 
1309
- ## CI lint reports and baselines
1310
-
1311
- Lint reports support CI annotations, test-report viewers, and readable reviews:
1312
-
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
1320
- ```
1321
-
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.
1323
-
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
1331
- ```
1332
-
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.
131
+ `--format github-actions` turns findings into annotations on the pull request. [JSON output, JUnit reports, and lint baselines →](https://scalar.com/tools/cli/ci-and-scripting)
1336
132
 
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
- ```
1359
-
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.
1361
-
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.
1363
-
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.
1365
-
1366
- ### Schema metadata
133
+ ## Commands
1367
134
 
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.
135
+ | Command | Description | Subcommands |
136
+ | --- | --- | --- |
137
+ | [`scalar auth`](https://scalar.com/tools/cli/commands/auth) | Log in to Scalar and manage your session | `login`, `whoami`, `logout` |
138
+ | [`scalar access-group`](https://scalar.com/tools/cli/commands/access-group) | Manage access groups and allowed email domains for the current team | `list`, `create`, `get`, `update`, `delete`, `domain add`, `domain remove` |
139
+ | [`scalar document`](https://scalar.com/tools/cli/commands/document) | Work with OpenAPI and AsyncAPI descriptions | `bundle`, `split`, `join`, `format`, `convert`, `markdown`, `mock`, `serve`, `share`, `validate`, `void`, `lint`, `upgrade` |
140
+ | [`scalar project`](https://scalar.com/tools/cli/commands/project) | Manage Scalar Docs projects | `list`, `get`, `init`, `check-config`, `create`, `preview`, `publish`, `rollback`, `deployments list`, `upgrade` |
141
+ | [`scalar registry`](https://scalar.com/tools/cli/commands/registry) | Manage API descriptions in the Scalar Registry | `publish`, `update`, `delete`, `list`, `get` |
142
+ | [`scalar team`](https://scalar.com/tools/cli/commands/team) | List and switch between your Scalar teams | `list`, `get`, `set` |
143
+ | [`scalar sdk`](https://scalar.com/tools/cli/commands/sdk) | Manage Scalar SDKs (Enterprise only) | `list`, `get`, `create`, `update`, `delete`, `build` |
144
+ | [`scalar schema`](https://scalar.com/tools/cli/commands/schema) | Manage shared schemas in the Scalar Registry | `delete`, `update`, `list`, `get`, `publish` |
145
+ | [`scalar readme`](https://scalar.com/tools/cli/commands/general#readme) | Open CLI documentation in your browser | `generate` |
146
+ | [`scalar upgrade`](https://scalar.com/tools/cli/commands/general#upgrade) | Upgrade the Scalar CLI to the latest version | |
147
+ | [`scalar context`](https://scalar.com/tools/cli/commands/general#context) | Print every command, argument, and option as JSON for AI agents | |
148
+ | [`scalar completion`](https://scalar.com/tools/cli/commands/general#completion) | Generate shell completion definitions | |
149
+
150
+ Run `scalar <command> --help` for options, or see the [command reference](https://scalar.com/tools/cli/commands).
151
+
152
+ ### Authentication details
153
+
154
+ Run `scalar auth whoami` to show your email, current team name and ID, role, and
155
+ authentication method (browser session or personal token). Use
156
+ `scalar auth whoami --json` for structured output with `email`,
157
+ `team: { uid, name }`, `role`, and `authentication` (`browser_session` or
158
+ `personal_token`). If the team name cannot be loaded, the team ID remains
159
+ available and JSON returns `null` for the name. Missing email or role values
160
+ also return `null`. Credentials are never included.