@scalar/cli 2.8.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 (111) hide show
  1. package/README.md +84 -1076
  2. package/chunks/action-25QMCP5G.js +122 -0
  3. package/chunks/{action-354TUG4H.js → action-2VF6LODL.js} +20 -16
  4. package/chunks/{action-XIUO64C7.js → action-5I4XDPPG.js} +20 -14
  5. package/chunks/action-6M5PTDF6.js +100 -0
  6. package/chunks/{action-NVI5DWFP.js → action-73ELLN3T.js} +8 -11
  7. package/chunks/{action-Y6NXJQ4H.js → action-7H3AWCHX.js} +21 -16
  8. package/chunks/{action-LLH4QPXM.js → action-BRSLSOE5.js} +19 -18
  9. package/chunks/{action-EOAVVL52.js → action-CQQCKSNS.js} +17 -22
  10. package/chunks/action-D5QWDNQ2.js +65 -0
  11. package/chunks/{action-Y7OUGD56.js → action-DQDHBOLJ.js} +34 -31
  12. package/chunks/{action-5SK5NE7E.js → action-EYPYQQVM.js} +18 -23
  13. package/chunks/{action-YRX6SN5F.js → action-FMA5ECUA.js} +12 -10
  14. package/chunks/{action-7PEQXDWT.js → action-GXDJLF2G.js} +134 -25
  15. package/chunks/action-HUICEXJZ.js +75 -0
  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-UIKH4SZX.js → action-J5TO3UJW.js} +32 -26
  20. package/chunks/{action-H6OUJWWM.js → action-KC3ZCNDR.js} +17 -22
  21. package/chunks/{action-6BYGBXRC.js → action-L7TMS3Q3.js} +44 -37
  22. package/chunks/{action-GWXLHL2Z.js → action-LAAHRDSR.js} +5 -4
  23. package/chunks/{action-FCAYFPVR.js → action-LR75GHBA.js} +14 -11
  24. package/chunks/action-MJMLQFLT.js +1552 -0
  25. package/chunks/action-NHU4CUKT.js +130 -0
  26. package/chunks/action-NKTFNFU7.js +64 -0
  27. package/chunks/{action-F7A2K74G.js → action-NMW5WPD2.js} +12 -16
  28. package/chunks/{action-VOFDW3U2.js → action-OTPXODUE.js} +8 -7
  29. package/chunks/{action-43YBNBDR.js → action-RPCDNGCI.js} +54 -39
  30. package/chunks/{action-QQZLPI42.js → action-RQCXSJPZ.js} +55 -27
  31. package/chunks/action-SOYSVG67.js +147 -0
  32. package/chunks/action-Y7EBKCUU.js +16 -0
  33. package/chunks/{action-WFDNRA7D.js → action-YN4TE7TG.js} +24 -23
  34. package/chunks/{action-AQRPFQKI.js → action-ZGNVWTHZ.js} +14 -12
  35. package/chunks/action-ZKKRPLDK.js +64 -0
  36. package/chunks/{action-HT2DJ34Z.js → action-ZUZL7R3H.js} +20 -15
  37. package/chunks/{actions-OGIVBQC7.js → actions-S6K76HCW.js} +46 -19
  38. package/chunks/{agent-ASPV3R5U.js → agent-IRNEV4K5.js} +46 -9
  39. package/chunks/{asyncapi-QNFKXHEI.js → asyncapi-WQPIQMEZ.js} +15 -10
  40. package/chunks/{build.action-NM6CAE5F.js → build.action-CLBVKFWD.js} +28 -24
  41. package/chunks/chunk-25XERWCE.js +1058 -0
  42. package/chunks/chunk-3RIUDHLG.js +467 -0
  43. package/chunks/{chunk-MLSZVVTT.js → chunk-3TFOA64C.js} +19 -8
  44. package/chunks/{chunk-HGOD6THU.js → chunk-4JKXZ5CF.js} +12 -25
  45. package/chunks/{chunk-C2KAWRIX.js → chunk-5ENKYZA4.js} +1 -1
  46. package/chunks/{chunk-W24BETFG.js → chunk-5L7V7RCH.js} +10 -10
  47. package/chunks/chunk-6PSYZO3U.js +24 -0
  48. package/chunks/{chunk-IMG35UXX.js → chunk-ALYM4ZB2.js} +1 -1
  49. package/chunks/chunk-AVZFSWPD.js +37 -0
  50. package/chunks/{chunk-5UHLAJQD.js → chunk-BQYVSPAI.js} +36 -10
  51. package/chunks/{chunk-XXSQUBXS.js → chunk-CSSTCHHF.js} +6212 -4642
  52. package/chunks/chunk-DFOZG7ZV.js +15 -0
  53. package/chunks/{chunk-22HYZ7LE.js → chunk-DQD2753S.js} +3 -3
  54. package/chunks/{action-F2ZJNURT.js → chunk-EBNFCIKS.js} +7 -10
  55. package/chunks/{chunk-EXY3ZTV4.js → chunk-F3OPMYME.js} +143 -301
  56. package/chunks/{chunk-FDC2IESH.js → chunk-FG5AOTDN.js} +8519 -14702
  57. package/chunks/chunk-GKCVATQJ.js +92 -0
  58. package/chunks/{chunk-PH3WFNXJ.js → chunk-GMHIK5K2.js} +1 -1
  59. package/chunks/{chunk-GTV2BVXV.js → chunk-GYR5E6RB.js} +2 -2
  60. package/chunks/{chunk-OJ2EWIJH.js → chunk-HZN6IIPZ.js} +11 -6
  61. package/chunks/{chunk-IKT5F47M.js → chunk-I57ID5K7.js} +24 -11
  62. package/chunks/{chunk-BPGFSSUH.js → chunk-KOD2HX5I.js} +1 -1
  63. package/chunks/{chunk-L3UXDCBI.js → chunk-LOLVJNI5.js} +4 -4
  64. package/chunks/{chunk-KCCFN4F7.js → chunk-MN2AFJXM.js} +36 -29
  65. package/chunks/{chunk-UXJ753NV.js → chunk-N5CJ5MTY.js} +5 -13
  66. package/chunks/chunk-NAC63XJF.js +10 -0
  67. package/chunks/{chunk-2OCWX42S.js → chunk-NWJ37GI2.js} +166 -22
  68. package/chunks/{chunk-3ZJYGGAA.js → chunk-ORCUZITN.js} +1 -1
  69. package/chunks/chunk-QMLRYD76.js +24 -0
  70. package/chunks/{chunk-KKRGBXCE.js → chunk-SEURG74P.js} +303 -209
  71. package/chunks/{chunk-R5LK6VPY.js → chunk-SOV4POMS.js} +370 -264
  72. package/chunks/chunk-T34TL6KL.js +222 -0
  73. package/chunks/{chunk-5DEU2DVL.js → chunk-U6VE6JOS.js} +3 -15
  74. package/chunks/{chunk-YILQODZF.js → chunk-UFSFY7Z4.js} +23 -20
  75. package/chunks/{chunk-6YPQGVF4.js → chunk-ULRJZXMS.js} +1 -1
  76. package/chunks/chunk-US54KYOJ.js +131 -0
  77. package/chunks/chunk-V6LUKXBV.js +37 -0
  78. package/chunks/{chunk-5JLVQVKO.js → chunk-VRZSDUZK.js} +190 -152
  79. package/chunks/chunk-VUXPDHTQ.js +22 -0
  80. package/chunks/chunk-XP5UM7SF.js +21 -0
  81. package/chunks/chunk-Y6XGC4K5.js +311 -0
  82. package/chunks/{create.action-FUQ2BVJA.js → create.action-ITEOQ644.js} +34 -30
  83. package/chunks/{delete.action-47E66R3I.js → delete.action-77MFPLUN.js} +30 -26
  84. package/chunks/{delete.action-BTDFH7WY.js → delete.action-C6VX4S5Q.js} +30 -26
  85. package/chunks/{get.action-XC7KC2JO.js → get.action-3BP4FHZC.js} +20 -14
  86. package/chunks/get.action-LNBOWUVE.js +95 -0
  87. package/chunks/list.action-6CRFQPJT.js +156 -0
  88. package/chunks/list.action-KR5YIDR4.js +126 -0
  89. package/chunks/{publish.action-OS27XOX4.js → publish.action-YBORRPBM.js} +49 -42
  90. package/chunks/query-WKATAJJ6.js +129 -0
  91. package/chunks/scripts-6CI6U32J.js +102 -0
  92. package/chunks/{update.action-AEIBLCWD.js → update.action-O7TSXDGV.js} +34 -27
  93. package/chunks/{update.action-ZMS4CQ3T.js → update.action-QZI7M2MV.js} +34 -27
  94. package/index.js +579 -382
  95. package/package.json +15 -14
  96. package/skills/scalar-cli/SKILL.md +52 -46
  97. package/template.md +71 -136
  98. package/chunks/action-CA4QYPI6.js +0 -125
  99. package/chunks/action-JAHFRYWZ.js +0 -423
  100. package/chunks/action-KTYOCA2V.js +0 -229
  101. package/chunks/action-LEUD5P2U.js +0 -92
  102. package/chunks/action-LXGXKXZZ.js +0 -72
  103. package/chunks/action-W3C53GPH.js +0 -54
  104. package/chunks/action-YLF2G4G5.js +0 -37
  105. package/chunks/chunk-6XWCMJDB.js +0 -404
  106. package/chunks/chunk-K74E42RV.js +0 -7311
  107. package/chunks/chunk-QVQ4PNVL.js +0 -610
  108. package/chunks/chunk-XEDGMZJD.js +0 -366
  109. package/chunks/list.action-LXKEUYKO.js +0 -116
  110. package/chunks/list.action-OFGLMRE7.js +0 -95
  111. package/docs.html +0 -6245
package/package.json CHANGED
@@ -5,14 +5,14 @@
5
5
  "engines": {
6
6
  "node": ">=24"
7
7
  },
8
- "version": "2.8.0",
8
+ "version": "2.11.0",
9
9
  "keywords": [
10
10
  "scalar",
11
11
  "openapi",
12
12
  "swagger",
13
13
  "cli"
14
14
  ],
15
- "description": "A command-line interface to work with OpenAPI files",
15
+ "description": "Validate, lint, bundle, mock, and preview OpenAPI and AsyncAPI descriptions, and publish them to Scalar",
16
16
  "type": "module",
17
17
  "bin": {
18
18
  "scalar": "./index.js"
@@ -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
  }
@@ -1,17 +1,17 @@
1
1
  ---
2
2
  name: scalar-cli
3
- description: "Operate the Scalar CLI (`scalar`, or `npx @scalar/cli`) to validate, lint, format, bundle, split, upgrade, mock, and preview OpenAPI documents, and to publish API references, docs projects, registry entries, schemas, and SDKs to Scalar. Use when a task involves the Scalar CLI or working with OpenAPI documents through Scalar."
3
+ description: "Operate the Scalar CLI (`scalar`, or `npx @scalar/cli`) to validate, lint, format, bundle, split, upgrade, mock, and preview OpenAPI and AsyncAPI descriptions, and to publish API Reference documentation, Scalar Docs projects, Scalar Registry entries, schemas, and SDKs to Scalar. Use when a task involves the Scalar CLI or working with API descriptions through Scalar."
4
4
  ---
5
5
 
6
6
  # Scalar CLI
7
7
 
8
- CLI to work with your OpenAPI files (`@scalar/cli` 2.8.0).
8
+ Validate, lint, bundle, mock, and preview OpenAPI and AsyncAPI descriptions, and publish them to Scalar (`@scalar/cli` 2.11.0).
9
9
 
10
10
  ## Operating notes
11
11
 
12
12
  - Run `scalar <command>` when the CLI is installed, or `npx @scalar/cli <command>` when it is not.
13
13
  - Run `scalar context` for this command tree as JSON, or `scalar <command> --help` for a single command.
14
- - Authenticate with a personal token: `scalar auth login --token <token>`, or set `SCALAR_API_KEY` and run `scalar auth login`. Both store the session on disk for later commands. Without a token, `scalar auth login` opens a browser and waits for a person to sign in, so do not run it that way. Check the session with `scalar auth whoami`.
14
+ - Log in with a personal token: `scalar auth login --token <token>`, or set `SCALAR_API_KEY` and run `scalar auth login`. Both store the session on disk for later commands. Without a token, `scalar auth login` opens a browser and waits for a person to log in, so do not run it that way. Check the session with `scalar auth whoami`.
15
15
  - Many commands prompt when a value is left out, such as a slug, a team, or a confirmation before overwriting a file, and a prompt blocks a non-interactive run. Pass every value as an argument or flag: for example `--output` on `document bundle` and `document upgrade`, `--yes` on `project rollback`, and `--force` on `project init`.
16
16
  - Results go to stdout. Errors go to stderr, prefixed with `[ERROR]`.
17
17
 
@@ -24,54 +24,60 @@ CLI to work with your OpenAPI files (`@scalar/cli` 2.8.0).
24
24
 
25
25
  Run `scalar context` for the arguments, options, defaults, and choices of each command.
26
26
 
27
- - `scalar readme [options] [command]`: Open documentation for the CLI
28
- - `scalar readme generate [options]`: Self generate documentation for the cli
29
- - `scalar upgrade [options]`: Upgrade current version of your cli
27
+ - `scalar readme [options] [command]`: Open CLI documentation in your browser
28
+ - `scalar readme generate [options]`: Generate the CLI README from the command tree
29
+ - `scalar upgrade [options]`: Upgrade the Scalar CLI to the latest version
30
30
  - `scalar context [options]`: Print every command, argument, and option as JSON for AI agents
31
- - `scalar auth login [options]`: Login to scalar
32
- - `scalar auth whoami [options]`: Display the current user
33
- - `scalar auth logout [options]`: Logout from scalar
31
+ - `scalar completion [options] <shell>`: Generate shell completion definitions
32
+ - `scalar auth login [options]`: Log in to Scalar
33
+ - `scalar auth whoami [options]`: Show the logged-in user and current team
34
+ - `scalar auth logout [options]`: Log out of Scalar
35
+ - `scalar access-group list [options]`: List access groups for the current team
34
36
  - `scalar access-group create [options] <slug>`: Create an access group (Pro or above)
35
37
  - `scalar access-group get [options] <slug>`: Get an access group and its allowlists
36
38
  - `scalar access-group update [options] <slug>`: Update access group metadata
37
39
  - `scalar access-group delete [options] <slug>`: Delete an access group and remove its project assignments
38
40
  - `scalar access-group domain add [options] <slug> <domain>`: Add an exact email domain to an access group
39
41
  - `scalar access-group domain remove [options] <slug> <domain>`: Remove an exact email domain from an access group
40
- - `scalar document bundle [options] [file|url]`: Bundle an OpenAPI document by resolving all references and external dependencies
41
- - `scalar document split [options] [file|url]`: Split OpenAPI or AsyncAPI documents into small chunks
42
- - `scalar document join [options] <files...>`: Merge multiple OpenAPI or AsyncAPI documents into a single unified document
43
- - `scalar document format [options] [file|url]`: Format an OpenAPI or AsyncAPI file
44
- - `scalar document convert [options] [file|url]`: Convert a Postman collection to an OpenAPI document
45
- - `scalar document markdown [options] [file|url]`: Generate Markdown from an OpenAPI file
46
- - `scalar document mock [options] [file|url]`: Mock an OpenAPI API or AsyncAPI WebSocket and SSE channels
47
- - `scalar document serve [options] [file|url]`: Serve an API Reference from an OpenAPI or AsyncAPI file
48
- - `scalar document share [options] [file]`: Share an OpenAPI or AsyncAPI file
49
- - `scalar document validate [options] [file|url]`: Validate an OpenAPI or AsyncAPI file
50
- - `scalar document void [options]`: Boot a server to mirror HTTP requests
51
- - `scalar document lint [options] [file|url]`: Lint your OpenAPI or AsyncAPI file using spectral rules
52
- - `scalar document upgrade [options] [file|url]`: Upgrade an OpenAPI or AsyncAPI document to version 3.1
53
- - `scalar project init [options]`: Create a new Scalar Docs project.
54
- - `scalar project check-config [options] [file]`: Check a Scalar Configuration file
55
- - `scalar project create [options]`: Create a new project that is not linked to a github project.
56
- - `scalar project preview [options] [config]`: Preview scalar guides
57
- - `scalar project publish [options]`: Publish new build for a github sync project that is not linked.
42
+ - `scalar document bundle [options] [file|url]`: Bundle external references into a single API description
43
+ - `scalar document split [options] [file|url]`: Split an OpenAPI or AsyncAPI description into referenced JSON files
44
+ - `scalar document join [options] <files...>`: Join API descriptions of the same format into one description
45
+ - `scalar document format [options] [file|url]`: Format an OpenAPI or AsyncAPI description
46
+ - `scalar document convert [options] [file|url]`: Convert a Postman collection to an OpenAPI description
47
+ - `scalar document markdown [options] [file|url]`: Generate Markdown documentation from an OpenAPI description
48
+ - `scalar document mock [options] [file|url]`: Run a Mock Server for OpenAPI operations or AsyncAPI WebSocket and SSE channels
49
+ - `scalar document serve [options] [file|url]`: Serve API Reference documentation from an OpenAPI or AsyncAPI description
50
+ - `scalar document share [options] [file]`: Publish an OpenAPI or AsyncAPI description to a public sandbox
51
+ - `scalar document validate [options] [file|url]`: Validate an OpenAPI or AsyncAPI description
52
+ - `scalar document void [options]`: Mirror HTTP requests with a local server
53
+ - `scalar document lint [options] [file|url]`: Lint an OpenAPI or AsyncAPI description with Spectral rules
54
+ - `scalar document upgrade [options] [file|url]`: Upgrade an API description to OpenAPI 3.1 or the latest supported AsyncAPI version
55
+ - `scalar project list [options]`: List projects and their slugs for the current team
56
+ - `scalar project get [options] <slug>`: Show project details for the current team
57
+ - `scalar project init [options]`: Initialize a local Scalar Docs project
58
+ - `scalar project check-config [options] [file]`: Validate a Scalar configuration file
59
+ - `scalar project create [options]`: Create a Scalar project without a linked GitHub repository
60
+ - `scalar project preview [options] [config]`: Preview a Scalar Docs project locally
61
+ - `scalar project publish [options]`: Publish a new build of a Scalar project
58
62
  - `scalar project rollback [options]`: Roll the live deployment back to a previously deployed build.
59
- - `scalar project deployments list [options]`: List the production deployment history for a project.
60
- - `scalar project upgrade [options] [config]`: Upgrade scalar project
61
- - `scalar registry publish [options] [file]`: Publish an OpenAPI document to the Scalar registry
62
- - `scalar registry update [options] [namespace] [slug]`: Update document metadata on scalar registry
63
- - `scalar registry delete [options] [namespace] [slug]`: Delete a document from scalar registry
64
- - `scalar registry list [options]`: List all registry APIs for a team namespace
65
- - `scalar registry get [options] [namespace] [slug]`: Get a document version from scalar registry
66
- - `scalar team list [options]`: List all teams current user is part of
67
- - `scalar team set [options]`: Set current active team for the user
68
- - `scalar sdk list [options]`: List all SDKs for a team namespace
69
- - `scalar sdk create [options]`: Create a new SDK. The SDK is created in the namespace of the API it is built from.
70
- - `scalar sdk update [options]`: Update SDK metadata.
71
- - `scalar sdk delete [options]`: Delete an SDK.
72
- - `scalar sdk build [options]`: Build an SDK.
73
- - `scalar schema delete [options]`: Delete a schema.
74
- - `scalar schema update [options]`: Update schema metadata.
75
- - `scalar schema list [options]`: List all schemas for a team namespace
76
- - `scalar schema get [options] [namespace] [slug]`: Get a schema document version from the Scalar registry
77
- - `scalar schema publish [options] [file]`: Publish a shared schema to the Scalar registry
63
+ - `scalar project deployments list [options]`: List production deployments for a project
64
+ - `scalar project upgrade [options] [config]`: Upgrade a Scalar Docs configuration
65
+ - `scalar registry publish [options] [file]`: Publish an OpenAPI description to the Scalar Registry
66
+ - `scalar registry update [options] [namespace] [slug]`: Update API description metadata in the Scalar Registry
67
+ - `scalar registry delete [options] [namespace] [slug]`: Delete an API description from the Scalar Registry
68
+ - `scalar registry list [options]`: List Scalar Registry API descriptions in a team namespace
69
+ - `scalar registry get [options] [namespace] [slug]`: Download an API description version from the Scalar Registry
70
+ - `scalar team list [options]`: List your Scalar teams
71
+ - `scalar team get [options]`: Show the current team and its namespaces
72
+ - `scalar team set [options]`: Select the current team
73
+ - `scalar sdk list [options]`: List SDKs in a team namespace
74
+ - `scalar sdk get [options]`: Inspect SDK metadata, API source, versions, and build status
75
+ - `scalar sdk create [options]`: Create an SDK in the namespace of its source API
76
+ - `scalar sdk update [options]`: Update SDK metadata
77
+ - `scalar sdk delete [options]`: Delete an SDK
78
+ - `scalar sdk build [options]`: Start an SDK build
79
+ - `scalar schema delete [options]`: Delete a shared schema
80
+ - `scalar schema update [options]`: Update shared schema metadata
81
+ - `scalar schema list [options]`: List shared schemas in a team namespace
82
+ - `scalar schema get [options] [namespace] [slug]`: Download a shared schema version from the Scalar Registry
83
+ - `scalar schema publish [options] [file]`: Publish a shared schema to the Scalar Registry
package/template.md CHANGED
@@ -2,211 +2,146 @@
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
- ## Access groups
19
-
20
- Manage access groups and allowed email domains for your current team:
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 access-group create partners --name Partners --domain example.com
25
- scalar access-group get partners --json
26
- scalar access-group update partners --name "Partner access"
27
- scalar access-group domain add partners partner.com
28
- scalar access-group domain remove partners partner.com
29
- scalar access-group delete partners --yes
12
+ npx @scalar/cli document validate openapi.yaml
30
13
  ```
31
14
 
32
- Creation requires Pro or above, and mutations require docs edit permission. Commands use your existing login and selected team; CI can authenticate with `scalar auth login --token <personal-token>`. Group arguments are slugs, not UIDs. Rename with `update <slug> --new-slug <new-slug>`, then use the new slug in later commands.
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)
33
16
 
34
- Use `--json` for machine-readable output: create/get print the group object, while successful updates, deletions and domain mutations print `null`. Errors go to stderr and exit nonzero. Deletion prompts in a terminal; pass `--yes` for unattended deletion or when using `--json`.
17
+ ## Common tasks
35
18
 
36
- Domains are exact email domains, with no wildcards or implicit subdomain matching. Matching preserves existing case-sensitive behavior. Groups support up to 1,000 domains; domain add/remove leaves other domains and individual email entries intact. Creating a group does not assign it to resources or change their privacy settings. Deleting a group removes its project assignments.
19
+ Every example works with `npx @scalar/cli` in place of `scalar` if you have not installed the CLI.
37
20
 
38
- ## Documentation
39
-
40
- 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)
41
-
42
- ## Quickstart
21
+ ### Validate and lint an API description
43
22
 
44
23
  ```bash
45
- 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
46
27
  ```
47
28
 
48
- ## Installation
49
-
50
- ### Standalone CLI (no Node.js required)
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)
51
30
 
52
- Install the latest stable release without Node.js, npm, or administrator access.
53
-
54
- macOS and Linux (Bash):
31
+ ### Bundle split files into one
55
32
 
56
33
  ```bash
57
- 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
58
36
  ```
59
37
 
60
- Windows (PowerShell):
61
-
62
- ```powershell
63
- irm https://cdn.scalar.com/cli/install.ps1 | iex
64
- ```
38
+ Pulls every external `$ref` into a single file. `--treeShake` drops components nothing uses. The input can be a URL.
65
39
 
66
- 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.
40
+ ### Preview the API reference
67
41
 
68
- 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.
69
-
70
- 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.
42
+ ```bash
43
+ scalar document serve openapi.yaml --watch
44
+ ```
71
45
 
72
- ### npm
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).
73
47
 
74
- If you already use Node.js, install the CLI with npm:
48
+ ### Mock the API
75
49
 
76
50
  ```bash
77
- npm -g install @scalar/cli
51
+ scalar document mock openapi.yaml --watch
78
52
  ```
79
53
 
80
- Otherwise just prefix all commands with `npx @scalar/cli` instead of `scalar`. That’s fine, too.
54
+ Starts a mock server that answers with the examples and schemas in your document, so you can try requests before the API exists.
81
55
 
82
- ### Conflict: EXIST: file already exists
83
-
84
- 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:
56
+ ### Upgrade and convert
85
57
 
86
58
  ```bash
87
- npm -g --force install @scalar/cli
59
+ scalar document upgrade swagger.json --output openapi.json
60
+ scalar document convert postman-collection.json --output openapi.json
88
61
  ```
89
62
 
90
- Or, if you want to keep using the other `scalar` CLI, you can just stick to `npx` (or `pnpm dlx`):
63
+ Upgrades Swagger 2.0 and OpenAPI 3.0 to OpenAPI 3.1, and converts Postman collections to OpenAPI.
91
64
 
92
- ```bash
93
- # Execute without installation (npm)
94
- npx @scalar/cli help
65
+ ### Publish to Scalar
95
66
 
96
- # Execute without installation (pnpm)
97
- pnpm dlx @scalar/cli help
67
+ ```bash
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
98
72
  ```
99
73
 
100
- ## API Reference configuration
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`.
101
75
 
102
- Pass API Reference options as a JSON object:
76
+ ## Install
103
77
 
104
- ```sh
105
- scalar document serve openapi.yaml --config ./reference.config.json
106
- ```
78
+ Standalone binary, no Node.js required:
107
79
 
108
- ```json
109
- {
110
- "orderRequiredPropertiesFirst": false,
111
- "theme": "purple"
112
- }
80
+ ```bash
81
+ # macOS and Linux
82
+ curl -fsSL https://cdn.scalar.com/cli/install.sh | bash
113
83
  ```
114
84
 
115
- The configuration path is relative to the current working directory. Configuration
116
- is loaded at startup; restart the command after changing it. `--watch` continues
117
- to watch the API document. Options requiring JavaScript functions are not supported
118
- in a JSON file.
119
-
120
- ## Authentication in automation
121
-
122
- Use `scalar auth login --token <personal-token>` to authenticate without a browser.
123
- Alternatively, set `SCALAR_API_KEY`. When both are provided, `SCALAR_API_KEY` takes
124
- precedence over `--token`. Unset it to use a different explicit token.
85
+ ```powershell
86
+ # Windows (PowerShell)
87
+ irm https://cdn.scalar.com/cli/install.ps1 | iex
88
+ ```
125
89
 
126
- Supply required options in automation instead of relying on interactive prompts.
127
- For example, pass `--output` for document transformations.
90
+ Or with npm:
128
91
 
129
- ## Commands
92
+ ```bash
93
+ npm install --global @scalar/cli
94
+ ```
130
95
 
131
- <COMMANDS>
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.
132
97
 
133
- ## AI agents
98
+ ## Use with AI agents
134
99
 
135
- `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`:
136
101
 
137
102
  ```bash
138
103
  scalar context
139
104
  ```
140
105
 
141
- 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:
142
107
 
143
108
  ```bash
144
109
  mkdir -p .claude/skills
145
-
146
- # npm (global install)
147
110
  cp -r "$(npm root -g)/@scalar/cli/skills/scalar-cli" .claude/skills/
148
-
149
- # Standalone CLI on macOS or Linux (the installer links `scalar` into its release directory)
150
- cp -r "$(dirname "$(readlink "$(command -v scalar)")")/app/skills/scalar-cli" .claude/skills/
151
111
  ```
152
112
 
153
- With the standalone CLI on Windows, the skill is in `%LOCALAPPDATA%\Scalar\current\app\skills\scalar-cli`.
154
-
155
- ## GitHub Actions
156
-
157
- To validate your OpenAPI file in GitHub Actions, add this workflow:
113
+ ## Use in CI
158
114
 
159
115
  ```yml
160
- # .github/workflows/validate-openapi-file.yml
161
- name: Validate OpenAPI File
162
-
163
- on:
164
- push:
165
- branches:
166
- - main
167
- pull_request:
168
- branches:
169
- - main
116
+ # .github/workflows/openapi.yml
117
+ name: OpenAPI
118
+ on: [push, pull_request]
170
119
 
171
120
  jobs:
172
- validate:
121
+ lint:
173
122
  runs-on: ubuntu-latest
174
-
175
123
  steps:
176
- - uses: actions/checkout@v4
177
- - name: Use Node.js
178
- uses: actions/setup-node@v4
124
+ - uses: actions/checkout@v6
125
+ - uses: actions/setup-node@v6
179
126
  with:
180
127
  node-version: 24
181
- - name: Validate OpenAPI File
182
- # Replace `./my-openapi-file.yaml` with the correct path and filename for your project.
183
- run: npx @scalar/cli document validate ./my-openapi-file.yaml
184
- ```
185
-
186
- ## Development
187
-
188
- Set up the development environment:
189
-
190
- ```bash
191
- pnpm install
192
- pnpm @scalar/cli --version
128
+ - run: npx --yes @scalar/cli document lint openapi.yaml --format github-actions
193
129
  ```
194
130
 
195
- To symlink the package and use it globally on your machine:
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)
196
132
 
197
- ```bash
198
- pnpm cli:link
199
- scalar --version
200
- ```
201
-
202
- ### Docs preview from a local build
203
-
204
- `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).
133
+ ## Commands
205
134
 
206
- ## Community
135
+ <COMMANDS>
207
136
 
208
- We are API nerds. You too? Let’s chat on Discord: <https://discord.gg/scalar>
137
+ Run `scalar <command> --help` for options, or see the [command reference](https://scalar.com/tools/cli/commands).
209
138
 
210
- ## License
139
+ ### Authentication details
211
140
 
212
- The source code in this repository is licensed under [MIT](https://github.com/scalar/scalar/blob/main/LICENSE).
141
+ Run `scalar auth whoami` to show your email, current team name and ID, role, and
142
+ authentication method (browser session or personal token). Use
143
+ `scalar auth whoami --json` for structured output with `email`,
144
+ `team: { uid, name }`, `role`, and `authentication` (`browser_session` or
145
+ `personal_token`). If the team name cannot be loaded, the team ID remains
146
+ available and JSON returns `null` for the name. Missing email or role values
147
+ also return `null`. Credentials are never included.
@@ -1,125 +0,0 @@
1
- import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- createError,
4
- displayError
5
- } from "./chunk-3ZJYGGAA.js";
6
- import {
7
- readAndParseConfig,
8
- renderConfigError
9
- } from "./chunk-W24BETFG.js";
10
- import {
11
- CONFIG_FILE_DEFAULT,
12
- findConfig,
13
- legacyTo2_0_0
14
- } from "./chunk-XXSQUBXS.js";
15
- import {
16
- ConfigVersion
17
- } from "./chunk-5JLVQVKO.js";
18
- import "./chunk-K74E42RV.js";
19
- import "./chunk-KCCFN4F7.js";
20
- import "./chunk-6XWCMJDB.js";
21
- import {
22
- output
23
- } from "./chunk-T5HJUAWB.js";
24
- import "./chunk-XEDGMZJD.js";
25
- import "./chunk-IKT5F47M.js";
26
- import "./chunk-3MZYUBJ6.js";
27
-
28
- // src/domains/project/upgrade/action.ts
29
- import fs from "node:fs/promises";
30
- import path from "node:path";
31
- import { text } from "@clack/prompts";
32
- import as from "ansis";
33
- import { n } from "neverpanic";
34
- async function upgradeAction(__configPath) {
35
- const configPath = __configPath || findConfig() || await text({
36
- message: "Where is your configuration file located?",
37
- defaultValue: CONFIG_FILE_DEFAULT,
38
- placeholder: CONFIG_FILE_DEFAULT
39
- });
40
- const parseConfigResult = readAndParseConfig(configPath);
41
- if (!parseConfigResult.success) {
42
- renderConfigError(parseConfigResult.error);
43
- }
44
- if (parseConfigResult.success) {
45
- output.info().line(
46
- `${as.green("[SUCCESS]")} ${as.green("Configuration is valid:")} ${as.green(parseConfigResult.filePath)}`
47
- ).print();
48
- }
49
- const { config } = parseConfigResult;
50
- if (config.version === ConfigVersion.V2) {
51
- return output.info().title("Your Scalar configuration is already upgraded").message(
52
- "You are already on the latest Scalar docs version. No further action required."
53
- ).exit("success");
54
- }
55
- const upgradedConfigResult = n.fromUnsafe(
56
- () => legacyTo2_0_0(config),
57
- (originalError) => createError("FAILED_TO_UPGRADE_CONFIG_V1", originalError)
58
- );
59
- if (!upgradedConfigResult.success) {
60
- return output.error().title("Could not upgrade config.").message(upgradedConfigResult.error.code).message(displayError(upgradedConfigResult.error.detail)).exit("error");
61
- }
62
- const { upgradedConfig, legacyTheme, legacyFooter, legacyScript } = upgradedConfigResult.data;
63
- if (legacyTheme) {
64
- const writeUpgradedThemeResult = await n.fromUnsafe(
65
- () => fs.writeFile(
66
- path.resolve(
67
- path.dirname(parseConfigResult.filePath),
68
- config.root ?? "./",
69
- legacyTheme.path
70
- ),
71
- legacyTheme.cssString
72
- ),
73
- (originalError) => createError("FAILED_TO_WRITE_UPGRADED_THEME", originalError)
74
- );
75
- if (!writeUpgradedThemeResult.success) {
76
- return output.error().title("Could not save upgraded theme.").message(writeUpgradedThemeResult.error.code).message(displayError(writeUpgradedThemeResult.error.detail)).exit("error");
77
- }
78
- }
79
- if (legacyFooter) {
80
- const writeUpgradedFooterResult = await n.fromUnsafe(
81
- () => fs.writeFile(
82
- path.resolve(
83
- path.dirname(parseConfigResult.filePath),
84
- config.root ?? "./",
85
- legacyFooter.path
86
- ),
87
- legacyFooter.footerString
88
- ),
89
- (originalError) => createError("FAILED_TO_WRITE_UPGRADED_FOOTER", originalError)
90
- );
91
- if (!writeUpgradedFooterResult.success) {
92
- return output.error().title("Could not save upgraded footer.").message(writeUpgradedFooterResult.error.code).message(displayError(writeUpgradedFooterResult.error.detail)).exit("error");
93
- }
94
- }
95
- if (legacyScript) {
96
- const writeUpgradedScriptResult = await n.fromUnsafe(
97
- () => fs.writeFile(
98
- path.resolve(
99
- path.dirname(parseConfigResult.filePath),
100
- config.root ?? "./",
101
- legacyScript.path
102
- ),
103
- legacyScript.scriptString
104
- ),
105
- (originalError) => createError("FAILED_TO_WRITE_UPGRADED_SCRIPT", originalError)
106
- );
107
- if (!writeUpgradedScriptResult.success) {
108
- return output.error().title("Could not save upgraded head script.").message(writeUpgradedScriptResult.error.code).message(displayError(writeUpgradedScriptResult.error.detail)).exit("error");
109
- }
110
- }
111
- const writeUpgradedConfigResult = await n.fromUnsafe(
112
- () => fs.writeFile(
113
- parseConfigResult.filePath,
114
- JSON.stringify(upgradedConfig, null, 2)
115
- ),
116
- (originalError) => createError("FAILED_TO_WRITE_UPGRADED_CONFIG", originalError)
117
- );
118
- if (!writeUpgradedConfigResult.success) {
119
- return output.error().title("Could not save upgraded config.").message(writeUpgradedConfigResult.error.code).message(displayError(writeUpgradedConfigResult.error.detail)).exit("error");
120
- }
121
- return output.info().title("Successfully upgraded Scalar Docs configuration!").message("Run `scalar project preview` to preview your project").exit("success");
122
- }
123
- export {
124
- upgradeAction
125
- };