# 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

## Documentation

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)

## 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: EXIST: 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

```
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:
  readme          Open documentation for the CLI
  upgrade         Upgrade current version of your cli
  auth            Manage authorization on scalar platform
  document        Manage local openapi file
  project         Manage scalar project
  registry        Manage your scalar registry
  team            Manage user teams
  sdk             Manage your Scalar SDKs (Enterprise Only)
  schema          Manage your Scalar schemas
  help [command]  display help for command
```

### readme
```
Usage: scalar readme [options] [command]

Open documentation for the CLI

Options:
  -h, --help          display help for command

Commands:
  generate [options]  Self generate documentation for the cli
```

#### generate
```
Usage: scalar readme generate [options]

Self generate documentation for the cli

Options:
  -o, --output [file]  Path where the documentation file will be written
  -h, --help           display help for command
```

### upgrade
```
Usage: scalar upgrade [options]

Upgrade current version of your cli

Options:
  -h, --help  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>        Email
  --password <password>  Password
  --token <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|url]   Bundle an OpenAPI specification by resolving all references and external dependencies
  split [options] [file|url]    Split your OpenAPI documents on small chunks
  join [options] <files...>     Merge multiple OpenAPI documents into a single unified document
  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
  upgrade [options] [file|url]  Upgrade OpenAPI document to version 3.1
  help [command]                display help for command
```

#### bundle
```
Usage: scalar document bundle [options] [file|url]

Bundle an OpenAPI specification by resolving all references and external dependencies

Arguments:
  file|url              Path to OpenAPI file or URL to bundle

Options:
  -o, --output <file>   Path to save the bundled output file
  --treeShake           Remove unused components from the bundled output
  --urlMap              Generate a map of resolved URLs in the bundled output
  --fetchLimit <limit>  Maximum number of URLs to fetch during bundling at the same time
  -h, --help            display help for command
```

#### split
```
Usage: scalar document split [options] [file|url]

Split your OpenAPI documents on small chunks

Arguments:
  file|url             Path to OpenAPI file or URL to split

Options:
  -o, --output <path>  Path to save the chunks
  -h, --help           display help for command
```

#### join
```
Usage: scalar document join [options] <files...>

Merge multiple OpenAPI documents into a single unified document

Arguments:
  files                                          Paths to the OpenAPI files to merge

Options:
  --output -o <file>                             Path to save the merged output file
  --prefix-components-with-path-value -p <path>  Dot-separated path to extract a prefix value from each input file for component names
  -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 <file>  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 <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 <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 <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 <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 <file|url>  Rule path or url
  -h, --help             display help for command
```

#### upgrade
```
Usage: scalar document upgrade [options] [file|url]

Upgrade OpenAPI document to version 3.1

Arguments:
  file|url             File or URL to validate

Options:
  -o, --output <file>  Path to save the upgraded output file
  -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 [options] [config]  Preview scalar guides
  publish [options]           Publish new build for a github sync project that is not linked.
  upgrade [config]            Upgrade scalar project
  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:
  -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                             Path to the Scalar configuration file (usually `scalar.config.json5` or `scalar.config.json`)

Options:
  -p, --port [port]                  port to run the server on. If the port is not available, it will select another one. (default: "7970")
  -h, --host [host]                  Specify which IP addresses the server should listen on.
  -L, --log-level <level>            Set the log level (debug, info, warn, error, trace) (default: "info")
  -F, --log-formatting <formatting>  Set the log formatting (pretty|none). Defaults to pretty formatting outside of CI. (default: "pretty")
  -N, --no-open                      Do not open the browser automatically
  --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 found in Scalar Dashboard
  -c, --config [config]  Your config file of the project
  -p, --preview          Publish in preview mode
  -g, --github           Publish from your linked remote GitHub repository
  -h, --help             display help for command
```

#### upgrade
```
Usage: scalar project upgrade [options] [config]

Upgrade scalar project

Arguments:
  config      Path to the Scalar configuration file (usually `scalar.config.json5` or `scalar.config.json`)

Options:
  -h, --help  display help for command
```

### registry
```
Usage: scalar registry [options] [command]

Manage your scalar registry

Options:
  -h, --help                           display help for command

Commands:
  publish [options] [file]             Publish an OpenAPI document to the Scalar registry
  update [options] [namespace] [slug]  Update document metadata on scalar registry
  delete [namespace] [slug]            Delete a document from scalar registry
  list [options]                       List all registry APIs for a team namespace
  help [command]                       display help for command
```

#### publish
```
Usage: scalar registry publish [options] [file]

Publish an OpenAPI document to the Scalar registry

Arguments:
  file                     OpenAPI file to upload

Options:
  --slug <slug>            Slug identifier for the registry entry. Defaults to title.
  --namespace <namespace>  Scalar team namespace
  --version <version>      API version (e.g. 0.1.0)
  --private                Make API private (default: false)
  --no-current             Do not set as the current version
  --force                  Force override an existing version (default: false)
  --bundle                 Bundle all external references before uploading
  --treeShake              Remove unused components from the bundled document
  --urlMap                 Generate a map of resolved URLs when bundling the document
  --fetchLimit <limit>     Maximum number of concurrent URLs to fetch when bundling the document
  -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
```

#### list
```
Usage: scalar registry list [options]

List all registry APIs for a team namespace

Options:
  --namespace <namespace>  Team namespace
  -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
```

### sdk
```
Usage: scalar sdk [options] [command]

Manage your Scalar SDKs (Enterprise Only)

Options:
  -h, --help        display help for command

Commands:
  list [options]    List all SDKs for a team namespace
  create [options]  Create a new SDK.
  update [options]  Update SDK metadata.
  delete [options]  Delete an SDK.
  build [options]   Create an SDK build.
  help [command]    display help for command
```

#### list
```
Usage: scalar sdk list [options]

List all SDKs for a team namespace

Options:
  --namespace <namespace>  Team namespace
  -h, --help               display help for command
```

#### create
```
Usage: scalar sdk create [options]

Create a new SDK.

Options:
  -a, --api <api>              Registry API slug
  -n, --namespace <namespace>  Team namespace
  -l, --language <language>    Language of your SDK (choices: "typescript", "python", "csharp", "java", "ruby", "php", "go")
  -h, --help                   display help for command
```

#### update
```
Usage: scalar sdk update [options]

Update SDK metadata.

Options:
  -s, --slug <slug>            SDK slug
  -n, --namespace <namespace>  Team namespace
  --title <title>              Title
  --isPrivate <isPrivate>      Privacy (public/private)
  -h, --help                   display help for command
```

#### delete
```
Usage: scalar sdk delete [options]

Delete an SDK.

Options:
  -s, --slug <slug>            SDK slug
  -n, --namespace <namespace>  Team namespace
  -h, --help                   display help for command
```

#### build
```
Usage: scalar sdk build [options]

Create an SDK build.

Options:
  -s, --slug <slug>            SDK slug
  -n, --namespace <namespace>  Team namespace
  -v, --version <version>      SDK Version
  -h, --help                   display help for command
```

### schema
```
Usage: scalar schema [options] [command]

Manage your Scalar schemas

Options:
  -h, --help                display help for command

Commands:
  delete [options]          Delete a schema.
  update [options]          Update schema metadata.
  list [options]            List all schemas for a team namespace
  publish [options] [file]  Publish a shared schema to the Scalar registry
  help [command]            display help for command
```

#### delete
```
Usage: scalar schema delete [options]

Delete a schema.

Options:
  -s, --slug <slug>            Schema slug
  -n, --namespace <namespace>  Team namespace
  -h, --help                   display help for command
```

#### update
```
Usage: scalar schema update [options]

Update schema metadata.

Options:
  -s, --slug <slug>            Schema slug
  -n, --namespace <namespace>  Team namespace
  --title <title>              Title
  --description <description>  Description
  --isPrivate <isPrivate>      Privacy (public/private)
  -h, --help                   display help for command
```

#### list
```
Usage: scalar schema list [options]

List all schemas for a team namespace

Options:
  --namespace <namespace>  Team namespace
  -h, --help               display help for command
```

#### publish
```
Usage: scalar schema publish [options] [file]

Publish a shared schema to the Scalar registry

Arguments:
  file                     OpenAPI file to upload

Options:
  --slug <slug>            Slug identifier for the registry entry. Defaults to title.
  --title <title>          Schema title
  --namespace <namespace>  Scalar team namespace
  --version <version>      API version (e.g. 0.1.0)
  --private                Make API private (default: false)
  --bundle                 Bundle all external references before uploading
  --treeShake              Remove unused components from the bundled document
  --urlMap                 Generate a map of resolved URLs when bundling the document
  --fetchLimit <limit>     Maximum number of concurrent URLs to fetch when bundling the document
  -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: 24
      - 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).
