# Scalar CLI [![Version](https://img.shields.io/npm/v/%40scalar/cli)](https://www.npmjs.com/package/@scalar/cli) [![Downloads](https://img.shields.io/npm/dm/%40scalar/cli)](https://www.npmjs.com/package/@scalar/cli) [![License](https://img.shields.io/npm/l/%40scalar%2Fapi-reference)](https://www.npmjs.com/package/@scalar/cli) [![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar) Command-line interface to work with OpenAPI files ## Features - Format & validate OpenAPI files - Upload your OpenAPI files to Scalar - Get a fully mocked API for testing purposes - Preview your API reference - ~~Bundle multiple OpenAPI files~~ (work in progress) ## Quickstart ```bash npx @scalar/cli help ``` ## Installation If you really want to become friends you should install the CLI: ```bash npm -g install @scalar/cli ``` Otherwise just prefix all commands with `npx @scalar/cli` instead of `scalar`. That’s fine, too. ### Conflict: EEXIST: file already exists 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: ```bash npm -g --force install @scalar/cli ``` Or, if you want to keep using the other `scalar` CLI, you can just stick to `npx` (or `pnpm dlx`): ```bash # Execute without installation (npm) npx @scalar/cli help # Execute without installation (pnpm) pnpm dlx @scalar/cli help ``` ## Commands ### scalar ``` Usage: scalar [options] [command] CLI to work with your OpenAPI files Options: -V, --version output the version number -h, --help display help for command Commands: auth Manage authorization on scalar platform document Manage local openapi file project Manage scalar project registry Manage your scalar registry team Manage user teams help [command] display help for command ``` #### auth ``` Usage: scalar auth [options] [command] Manage authorization on scalar platform Options: -h, --help display help for command Commands: login [options] Login to scalar whoami Display the current user logout Logout from scalar help [command] display help for command ``` ##### login ``` Usage: scalar auth login [options] Login to scalar Options: --email Email --password Password --token Personal token -h, --help display help for command ``` ##### whoami ``` Usage: scalar auth whoami [options] Display the current user Options: -h, --help display help for command ``` ##### logout ``` Usage: scalar auth logout [options] Logout from scalar Options: -h, --help display help for command ``` #### document ``` Usage: scalar document [options] [command] Manage local openapi file Options: -h, --help display help for command Commands: bundle [options] [file] Resolve all references in an OpenAPI file format [options] [file|url] Format an OpenAPI file mock [options] [file|url] Mock an API from an OpenAPI file serve [options] [file|url] Serve an API Reference from an OpenAPI file share [options] [file] Share an OpenAPI file validate [file|url] Validate an OpenAPI file void [options] Boot a server to mirror HTTP requests lint [options] [file|url] Lint your OpenAPI file using spectral rules help [command] display help for command ``` ##### bundle ``` Usage: scalar document bundle [options] [file] Resolve all references in an OpenAPI file Arguments: file file to bundle Options: -o, --output output file -h, --help display help for command ``` ##### format ``` Usage: scalar document format [options] [file|url] Format an OpenAPI file Arguments: file|url File or URL to format Options: -o, --output Output file -h, --help display help for command ``` ##### mock ``` Usage: scalar document mock [options] [file|url] Mock an API from an OpenAPI file Arguments: file|url OpenAPI file or URL to mock the server for Options: -w, --watch watch the file for changes -o, --once run the server only once and exit after that -p, --port set the HTTP port for the mock server -h, --help display help for command ``` ##### serve ``` Usage: scalar document serve [options] [file|url] Serve an API Reference from an OpenAPI file Arguments: file|url OpenAPI file or URL to show the reference for Options: -w, --watch watch the file for changes -o, --once run the server only once and exit after that -p, --port set the HTTP port for the API reference server -h, --help display help for command ``` ##### share ``` Usage: scalar document share [options] [file] Share an OpenAPI file Arguments: file file to share Options: -t, --token pass a token to update an existing sandbox -h, --help display help for command ``` ##### validate ``` Usage: scalar document validate [options] [file|url] Validate an OpenAPI file Arguments: file|url File or URL to validate Options: -h, --help display help for command ``` ##### void ``` Usage: scalar document void [options] Boot a server to mirror HTTP requests Options: -o, --once run the server only once and exit after that -p, --port set the HTTP port for the mock server -h, --help display help for command ``` ##### lint ``` Usage: scalar document lint [options] [file|url] Lint your OpenAPI file using spectral rules Arguments: file|url OpenAPI file path or url Options: -r, --rule Rule path or url -h, --help display help for command ``` #### project ``` Usage: scalar project [options] [command] Manage scalar project Options: -h, --help display help for command Commands: init [options] Create a new `scalar.config.json` file to configure where your OpenAPI file is placed. check-config [file] Check a Scalar Configuration file create [options] Create a new project that is not linked to a github project. preview [config] Preview scalar guides publish [options] Publish new build for a github sync project that is not linked. help [command] display help for command ``` ##### init ``` Usage: scalar project init [options] Create a new `scalar.config.json` file to configure where your OpenAPI file is placed. Options: -f, --file [file] your OpenAPI file -s, --subdomain [url] subdomain to publish on --force override existing configuration -h, --help display help for command ``` ##### check-config ``` Usage: scalar project check-config [options] [file] Check a Scalar Configuration file Arguments: file File to check Options: -h, --help display help for command ``` ##### create ``` Usage: scalar project create [options] Create a new project that is not linked to a github project. Options: -n, --name [name] name of your project -s, --slug [slug] project slug -h, --help display help for command ``` ##### preview ``` Usage: scalar project preview [options] [config] Preview scalar guides Arguments: config your config file of the project Options: -h, --help display help for command ``` ##### publish ``` Usage: scalar project publish [options] Publish new build for a github sync project that is not linked. Options: -s, --slug [slug] project slug -c, --config [config] your config file of the project -h, --help display help for command ``` #### registry ``` Usage: scalar registry [options] [command] Manage your scalar registry Options: -h, --help display help for command Commands: create [options] [file] Create a document on scalar registry update [options] [namespace] [slug] Update document metadata on scalar registry delete [namespace] [slug] Delete a document from scalar registry help [command] display help for command ``` ##### create ``` Usage: scalar registry create [options] [file] Create a document on scalar registry Arguments: file file to upload Options: --namespace Namespace --title Document title --description <description> Document description --doc-version <doc-version> Document version -h, --help display help for command ``` ##### update ``` Usage: scalar registry update [options] [namespace] [slug] Update document metadata on scalar registry Arguments: namespace namespace of document you want to update slug slug of document you want to update Options: --title <title> Document title --description <description> Document description -h, --help display help for command ``` ##### delete ``` Usage: scalar registry delete [options] [namespace] [slug] Delete a document from scalar registry Arguments: namespace Team namespace slug Managed doc slug Options: -h, --help display help for command ``` #### team ``` Usage: scalar team [options] [command] Manage user teams Options: -h, --help display help for command Commands: list List all teams current user is part of set [options] Set current active team for the user help [command] display help for command ``` ##### list ``` Usage: scalar team list [options] List all teams current user is part of Options: -h, --help display help for command ``` ##### set ``` Usage: scalar team set [options] Set current active team for the user Options: --team <team> Team uid -h, --help display help for command ``` ## GitHub Actions To validate your OpenAPI file in GitHub Actions, add this workflow: ```yml # .github/workflows/validate-openapi-file.yml name: Validate OpenAPI File on: push: branches: - main pull_request: branches: - main jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: 20 - name: Validate OpenAPI File # Replace `./my-openapi-file.yaml` with the correct path and filename for your project. # Or: run `npx @scalar/cli init` and add the config file to your repository. run: npx @scalar/cli validate ./my-openapi-file.yaml ``` ## Development Set up the development environment: ```bash pnpm install pnpm @scalar/cli --version ``` To symlink the package and use it globally on your machine: ```bash pnpm cli:link scalar --version ``` ## Community We are API nerds. You too? Let’s chat on Discord: <https://discord.gg/scalar> ## License The source code in this repository is licensed under [MIT](https://github.com/scalar/scalar/blob/main/LICENSE).