@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/package.json CHANGED
@@ -5,14 +5,14 @@
5
5
  "engines": {
6
6
  "node": ">=24"
7
7
  },
8
- "version": "2.10.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"
@@ -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.10.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,14 +24,14 @@ CLI to work with your OpenAPI files (`@scalar/cli` 2.10.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
31
  - `scalar completion [options] <shell>`: Generate shell completion definitions
32
- - `scalar auth login [options]`: Login to scalar
33
- - `scalar auth whoami [options]`: Display the current user
34
- - `scalar auth logout [options]`: Logout from scalar
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
35
  - `scalar access-group list [options]`: List access groups for the current team
36
36
  - `scalar access-group create [options] <slug>`: Create an access group (Pro or above)
37
37
  - `scalar access-group get [options] <slug>`: Get an access group and its allowlists
@@ -39,45 +39,45 @@ Run `scalar context` for the arguments, options, defaults, and choices of each c
39
39
  - `scalar access-group delete [options] <slug>`: Delete an access group and remove its project assignments
40
40
  - `scalar access-group domain add [options] <slug> <domain>`: Add an exact email domain to an access group
41
41
  - `scalar access-group domain remove [options] <slug> <domain>`: Remove an exact email domain from an access group
42
- - `scalar document bundle [options] [file|url]`: Bundle an OpenAPI document by resolving all references and external dependencies
43
- - `scalar document split [options] [file|url]`: Split OpenAPI or AsyncAPI documents into small chunks
44
- - `scalar document join [options] <files...>`: Merge multiple OpenAPI or AsyncAPI documents into a single unified document
45
- - `scalar document format [options] [file|url]`: Format an OpenAPI or AsyncAPI file
46
- - `scalar document convert [options] [file|url]`: Convert a Postman collection to an OpenAPI document
47
- - `scalar document markdown [options] [file|url]`: Generate Markdown from an OpenAPI file
48
- - `scalar document mock [options] [file|url]`: Mock an OpenAPI API or AsyncAPI WebSocket and SSE channels
49
- - `scalar document serve [options] [file|url]`: Serve an API Reference from an OpenAPI or AsyncAPI file
50
- - `scalar document share [options] [file]`: Share an OpenAPI or AsyncAPI file
51
- - `scalar document validate [options] [file|url]`: Validate an OpenAPI or AsyncAPI file
52
- - `scalar document void [options]`: Boot a server to mirror HTTP requests
53
- - `scalar document lint [options] [file|url]`: Lint your OpenAPI or AsyncAPI file using spectral rules
54
- - `scalar document upgrade [options] [file|url]`: Upgrade an OpenAPI or AsyncAPI document to version 3.1
55
- - `scalar project list [options]`: List projects and their slugs for the current team.
56
- - `scalar project get [options] <slug>`: Get project details for the current team.
57
- - `scalar project init [options]`: Create a new Scalar Docs project.
58
- - `scalar project check-config [options] [file]`: Check a Scalar Configuration file
59
- - `scalar project create [options]`: Create a new project that is not linked to a github project.
60
- - `scalar project preview [options] [config]`: Preview scalar guides
61
- - `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
62
62
  - `scalar project rollback [options]`: Roll the live deployment back to a previously deployed build.
63
- - `scalar project deployments list [options]`: List the production deployment history for a project.
64
- - `scalar project upgrade [options] [config]`: Upgrade scalar project
65
- - `scalar registry publish [options] [file]`: Publish an OpenAPI document to the Scalar registry
66
- - `scalar registry update [options] [namespace] [slug]`: Update document metadata on scalar registry
67
- - `scalar registry delete [options] [namespace] [slug]`: Delete a document from scalar registry
68
- - `scalar registry list [options]`: List all registry APIs for a team namespace
69
- - `scalar registry get [options] [namespace] [slug]`: Get a document version from scalar registry
70
- - `scalar team list [options]`: List all teams current user is part of
71
- - `scalar team get [options]`: Get the current team and its namespaces
72
- - `scalar team set [options]`: Set current active team for the user
73
- - `scalar sdk list [options]`: List all SDKs for a team namespace
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
74
  - `scalar sdk get [options]`: Inspect SDK metadata, API source, versions, and build status
75
- - `scalar sdk create [options]`: Create a new SDK. The SDK is created in the namespace of the API it is built from.
76
- - `scalar sdk update [options]`: Update SDK metadata.
77
- - `scalar sdk delete [options]`: Delete an SDK.
78
- - `scalar sdk build [options]`: Build an SDK.
79
- - `scalar schema delete [options]`: Delete a schema.
80
- - `scalar schema update [options]`: Update schema metadata.
81
- - `scalar schema list [options]`: List all schemas for a team namespace
82
- - `scalar schema get [options] [namespace] [slug]`: Get a schema document version from the Scalar registry
83
- - `scalar schema publish [options] [file]`: Publish a shared schema to the Scalar registry
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,333 +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
- ## 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.
30
-
31
- Use `scalar project list --json` for an array of project details and `scalar project get my-docs --json` for one object. Both include `uid`, `name`, `slug`, `provider`, `isPrivate`, `repository`, and `activeDeployment`. An unlinked repository or absent live deployment is `null`; the provider is `forgejo`, `github`, `bitbucket`, or `unlinked`. The live deployment describes the active build, not a failed or pending publish attempt.
32
-
33
- Project listing retrieves every page. On older servers that truncate the list without a continuation cursor, it exits with an error instead of printing an incomplete list. Errors go to stderr and exit nonzero.
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)
34
16
 
35
- ## Documentation
17
+ ## Common tasks
36
18
 
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)
19
+ Every example works with `npx @scalar/cli` in place of `scalar` if you have not installed the CLI.
38
20
 
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
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)
46
30
 
47
- ### Standalone CLI (no Node.js required)
48
-
49
- Install the latest stable release without Node.js, npm, or administrator access.
50
-
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):
38
+ Pulls every external `$ref` into a single file. `--treeShake` drops components nothing uses. The input can be a URL.
58
39
 
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.
66
-
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
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).
80
47
 
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:
48
+ ### Mock the API
82
49
 
83
50
  ```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`):
88
-
89
- ```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
59
+ scalar document upgrade swagger.json --output openapi.json
60
+ scalar document convert postman-collection.json --output openapi.json
124
61
  ```
125
62
 
126
- Open a new shell. Both `scalar` and `scalar-cli` use the same completion function.
63
+ Upgrades Swagger 2.0 and OpenAPI 3.0 to OpenAPI 3.1, and converts Postman collections to OpenAPI.
127
64
 
128
- ### Fish
65
+ ### Publish to Scalar
129
66
 
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
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
134
72
  ```
135
73
 
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 `>>`.
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`.
141
75
 
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.
76
+ ## Install
143
77
 
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`.
78
+ Standalone binary, no Node.js required:
145
79
 
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
80
+ ```bash
81
+ # macOS and Linux
82
+ curl -fsSL https://cdn.scalar.com/cli/install.sh | bash
152
83
  ```
153
84
 
154
- ```json
155
- {
156
- "orderRequiredPropertiesFirst": false,
157
- "theme": "purple"
158
- }
85
+ ```powershell
86
+ # Windows (PowerShell)
87
+ irm https://cdn.scalar.com/cli/install.ps1 | iex
159
88
  ```
160
89
 
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.
174
-
175
- ## Team discovery
176
-
177
- After logging in, run `scalar team list` to see your teams and their copyable UIDs. The current team is marked as the default. Use a UID with `scalar team set --team <uid>` to switch teams.
178
-
179
- Run `scalar team get` to see the current team's UID, name, slug, and namespaces. Both discovery commands support `--json` for scripts:
90
+ Or with npm:
180
91
 
181
92
  ```bash
182
- scalar team list --json
183
- scalar team get --json
93
+ npm install --global @scalar/cli
184
94
  ```
185
95
 
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
- <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.
191
97
 
192
- ## AI agents
98
+ ## Use with AI agents
193
99
 
194
- `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`:
195
101
 
196
102
  ```bash
197
103
  scalar context
198
104
  ```
199
105
 
200
- 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:
201
107
 
202
108
  ```bash
203
109
  mkdir -p .claude/skills
204
-
205
- # npm (global install)
206
110
  cp -r "$(npm root -g)/@scalar/cli/skills/scalar-cli" .claude/skills/
207
-
208
- # Standalone CLI on macOS or Linux (the installer links `scalar` into its release directory)
209
- cp -r "$(dirname "$(readlink "$(command -v scalar)")")/app/skills/scalar-cli" .claude/skills/
210
111
  ```
211
112
 
212
- With the standalone CLI on Windows, the skill is in `%LOCALAPPDATA%\Scalar\current\app\skills\scalar-cli`.
213
-
214
- ## Inspect SDKs
215
-
216
- Use your current team login to inspect an SDK by slug. The namespace defaults to the team's first namespace.
217
-
218
- ```bash
219
- scalar sdk get --slug widgets --namespace acme
220
- scalar sdk get --slug widgets --namespace acme --json
221
- scalar sdk list --namespace acme --json
222
- ```
223
-
224
- JSON output is a metadata object for `get` and an array for `list` (including `[]` when empty). It includes the linked registry API, tracked API version, target languages and slugs, current SDK version, version history with active build IDs, and the latest attempted build with per-language generation and Git sync status. The latest attempt may be a different version or have failed; it does not replace the current version or active artifacts. Timestamps are Unix seconds; absent builds and unlinked API sources are `null`. Generator configuration, repository auth bindings, and raw build messages are excluded.
225
-
226
- ## Registry metadata for scripts
227
-
228
- Use `scalar registry list --json` to write a JSON array to stdout. Without
229
- `--namespace`, the command uses the first namespace of your current team, just
230
- like the default table output. You must be logged in; errors go to stderr and
231
- exit with a nonzero status.
232
-
233
- ```bash
234
- scalar registry list --namespace scalar --json > registry-apis.json
235
- scalar registry get scalar demo-api --version 1.2.3 > openapi.json
236
- ```
237
-
238
- Each array entry contains `namespace` and `slug` (the coordinates accepted by
239
- `registry get`), `title` (a string, which may be empty), `version` (the current
240
- version served by default), and `isPrivate` (a boolean). JSON output includes
241
- only these metadata fields, without document content or credentials. An empty
242
- namespace returns `[]`. Omit `--json` for the human-readable table.
243
-
244
- ## GitHub Actions
245
-
246
- To validate your OpenAPI file in GitHub Actions, add this workflow:
113
+ ## Use in CI
247
114
 
248
115
  ```yml
249
- # .github/workflows/validate-openapi-file.yml
250
- name: Validate OpenAPI File
251
-
252
- on:
253
- push:
254
- branches:
255
- - main
256
- pull_request:
257
- branches:
258
- - main
116
+ # .github/workflows/openapi.yml
117
+ name: OpenAPI
118
+ on: [push, pull_request]
259
119
 
260
120
  jobs:
261
- validate:
121
+ lint:
262
122
  runs-on: ubuntu-latest
263
-
264
123
  steps:
265
- - uses: actions/checkout@v4
266
- - name: Use Node.js
267
- uses: actions/setup-node@v4
124
+ - uses: actions/checkout@v6
125
+ - uses: actions/setup-node@v6
268
126
  with:
269
127
  node-version: 24
270
- - name: Validate OpenAPI File
271
- # Replace `./my-openapi-file.yaml` with the correct path and filename for your project.
272
- run: npx @scalar/cli document validate ./my-openapi-file.yaml
128
+ - run: npx --yes @scalar/cli document lint openapi.yaml --format github-actions
273
129
  ```
274
130
 
275
- ## CI lint reports and baselines
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)
276
132
 
277
- Lint reports support CI annotations, test-report viewers, and readable reviews:
278
-
279
- ```sh
280
- scalar document lint openapi.yaml --format codeframe
281
- scalar document lint openapi.yaml --format markdown --output lint-results.md
282
- scalar document lint openapi.yaml --format summary
283
- scalar document lint openapi.yaml --format github-actions
284
- scalar document lint openapi.yaml --format json --output lint-results.json
285
- scalar document lint openapi.yaml --format junit --output lint-results.xml
286
- ```
287
-
288
- The default is `codeframe`, which shows source excerpts with severity colors and highlighted carets when terminal colors are enabled. `NO_COLOR=1` disables colors, and reports saved with `--output` are always plain text. Use `--format text` for the native report. `markdown` produces tables grouped by source, and `summary` counts findings by rule and severity. Machine-readable reports use 1-based locations; text retains engine-native coordinates. Codeframes omit excerpts for unavailable sources.
289
-
290
- `--max-problems <number>` limits displayed findings to 100 by default. Findings are ordered by severity, with errors first. Use `--max-problems 0` to hide all findings. Counts and the exit status always include every active finding, and baseline generation records all findings regardless of this limit. Summary rule counts cover the displayed findings; its final error/warning totals cover all findings. Truncation notices go to stderr, keeping JSON and XML valid.
291
-
292
- Reports go to stdout unless `--output` is given. Status, upgrade, and truncation notices go to stderr. Reports are written even when lint findings cause a nonzero exit. Both shell redirection and `--output` work:
293
-
294
- ```sh
295
- scalar document lint openapi.yaml --format json > lint-results.json
296
- scalar document lint openapi.yaml --format json --output lint-results.json
297
- ```
298
-
299
- Prefer `--output` in scripts when you want Scalar to check the destination against the input, custom ruleset, baseline, and referenced source files (including clean nested references and file aliases). Shell redirection is convenient for piping; the shell opens or truncates the destination before Scalar starts, so Scalar cannot protect that destination. Parent directories for `--output` must already exist.
300
-
301
- JSON follows Redocly's report shape: `totals` contains error, warning, and ignored counts; `version` is the Scalar CLI version; `problems` is the displayed findings array. Each problem includes `ruleId`, `severity` (`error`, `warn`, `info`, or `hint`), `message`, `suggest`, optional rule `reference`, and a `location` array. Locations contain `source.ref`, a JSON `pointer`, and 1-based `start`/`end` positions with `line` and `col`. Local sources are relative to the current directory; URLs remain absolute. Rule IDs and findings still come from Scalar's Vacuum/Spectral engines. Duplicate-operation-ID findings include the participating definitions, including referenced path items and callbacks. Reports preserve additional locations when supplied by the engine; totals and JUnit still count one testcase per finding, and ignore matching uses the primary location, with legacy native paths retained as matching candidates. Scalar does not yet provide Redocly's typo suggestions.
302
-
303
- GitHub Actions reports use error, warning, and notice annotations with start and end positions and available rule documentation links. Local files are relative to `GITHUB_WORKSPACE`, or the current directory outside Actions. Remote sources appear in the message without a repository file attachment. When saved with `--output`, annotations must subsequently be printed to the runner's stdout to become visible.
304
-
305
- JUnit groups findings into suites by source, with one testcase per displayed finding. To match Redocly, lint errors become XML `error` entries, warnings become `failure` entries, and information/hints become `system-out`. Warnings still do not make the lint command exit nonzero, and JUnit viewers classify those testcases as failed. The CLI lint report compatibility workflow verifies this behavior using the Java JUnit viewer in `dorny/test-reporter`. The `Scalar lint totals` suite records full error, warning, ignored, and hidden counts as properties. A clean run produces a valid zero-test report. Configure CI to upload reports even when the lint step fails.
306
-
307
- To adopt linting with existing findings:
308
-
309
- ```sh
310
- scalar document lint openapi.yaml --generate-ignore-file
311
- scalar document lint openapi.yaml --format github-actions
312
- ```
313
-
314
- Commit the generated `.scalar.lint-ignore.yaml`. Subsequent runs automatically read it from the current directory. `--ignore-file <file>` overrides that location for generation and linting, including an existing `.redocly.lint-ignore.yaml`. Relative paths resolve from the current directory; no parent-directory search is performed. If Scalar's file is absent, linting automatically falls back to `.redocly.lint-ignore.yaml`. You can also rename a Redocly ignore file to `.scalar.lint-ignore.yaml`; Scalar's file always wins when both exist. Generation defaults to Scalar's filename and leaves Redocly's file intact. Scalar does not read `redocly.yaml`.
315
-
316
- For OpenAPI with the default ruleset, imported mappings support the audited Redocly rules `info-contact`, `info-license`, `operation-description`, `operation-operationId`, `operation-operationId-url-safe` (mapped to Scalar's `operation-operationId-valid-in-url`), `no-path-trailing-slash` (`path-keys-no-trailing-slash`), `path-declaration-must-exist` (`path-declarations-must-exist`), `path-not-include-query`, `tag-description`, and `operation-singular-tag`. Missing-field pointers are adapted where the engines report the containing object. This does not enable rules that Scalar's default engine disables. Unsupported rules produce a notice on stderr; only exact Scalar rule/pointer matches apply to those entries. Severity-only overrides of these audited built-in rules retain migration support. Custom definitions, unknown inheritance, and AsyncAPI use exact Scalar identities. Redocly’s `operation-2xx-response` is not mapped to Scalar’s `operation-success-response`, which also accepts 3xx responses. Full custom-rule compatibility would require running Redocly itself.
317
-
318
- The YAML mapping uses Redocly's source → rule → JSON-pointer structure:
319
-
320
- ```yaml
321
- openapi.yaml:
322
- info-description:
323
- - '#/info'
324
- ```
325
-
326
- Local source paths are relative to the baseline directory. Matching ignores message, severity, and line changes. Mounted reference paths are resolved to physical source pointers, including nested references; older Scalar baselines using native mount paths continue to match. Path-key findings use the key location to distinguish specific path entries. Root pointers use `#`; `/` and `~` in property names use RFC 6901 escaping. Numeric and string path segments with the same pointer identify the same location.
133
+ ## Commands
327
134
 
328
- Generation records all current findings and exits successfully after writing the baseline. Generation serializes baseline reads and writes to preserve concurrent updates. A leftover `.lock` directory after an interrupted process must be removed only when no generator is running. Regeneration replaces only the selected input document's entries and preserves other inputs, including shared references. Scalar stores input ownership in a YAML comment (`scalar-owners`) that Redocly ignores. Keep that comment to retain shared-reference ownership; without it, imported entries belong to their source file. Manual edits to the mapping take precedence over comment metadata. Legacy Scalar version 1 baselines remain readable and are migrated to this mapping on regeneration.
135
+ <COMMANDS>
329
136
 
330
- Matched findings are omitted from reports. Only unmatched errors cause exit 1; warnings, information, and hints do not fail lint. Operational failures, malformed baselines, and missing explicitly selected baselines exit nonzero. A missing default baseline is allowed. Multiple findings at the same source/rule/pointer share one entry. Resolved entries remain harmless until regeneration but can suppress a recurrence; array reordering, document renames, or rule changes may produce new identities.
137
+ Run `scalar <command> --help` for options, or see the [command reference](https://scalar.com/tools/cli/commands).
331
138
 
332
- ### Schema metadata
139
+ ### Authentication details
333
140
 
334
- Use `scalar schema list --json` to discover schemas in the current team namespace, or pass `--namespace <namespace>` to choose one. The output is an array of objects with `namespace`, `slug`, `title`, `version`, and `isPrivate`. `version` is the latest semantic version, or `null` when there are no versions. An empty namespace returns `[]`. Schema content is omitted; use `scalar schema get` to download it.
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,37 +0,0 @@
1
- import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- apiService
4
- } from "./chunk-ATNTXKMS.js";
5
- import "./chunk-43WALAW3.js";
6
- import "./chunk-ZYBLQ5CT.js";
7
- import "./chunk-KHF2QXBG.js";
8
- import "./chunk-IPZP3VRA.js";
9
- import "./chunk-5ENKYZA4.js";
10
- import "./chunk-G4HRW2FZ.js";
11
- import "./chunk-35Z7VTJT.js";
12
- import "./chunk-WB6PWTMU.js";
13
- import "./chunk-DHZW7Q7U.js";
14
- import "./chunk-GYRQPDTK.js";
15
- import "./chunk-6M7TL2G2.js";
16
- import "./chunk-GLWTVLKM.js";
17
- import "./chunk-MNNGUUKJ.js";
18
- import {
19
- output
20
- } from "./chunk-T5HJUAWB.js";
21
- import "./chunk-ZGVZU6L2.js";
22
- import "./chunk-VVRUSQCY.js";
23
- import "./chunk-3MZYUBJ6.js";
24
-
25
- // src/domains/registry/delete/action.ts
26
- async function deleteAction(namespace, slug) {
27
- const client = await apiService();
28
- const logger = output.info().line().loader("Deleting the api document");
29
- const deleteDocument = await client.managedDocs.delete(namespace, slug);
30
- if (deleteDocument.error) {
31
- return output.error().title(deleteDocument.message).exit("error");
32
- }
33
- logger.update("loader", 0, { content: "Successfully deleted document." }).print();
34
- }
35
- export {
36
- deleteAction
37
- };