# Scalar CLI

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

## Quickstart

    npx @scalar/cli help

## Installation

If you really want to become friends you should install the CLI:

    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:

    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`):

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

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

    pnpm install
    pnpm @scalar/cli --version

To symlink the package and use it globally on your machine:

    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.