Scalar CLI

Validate, lint, bundle, mock, and preview OpenAPI and AsyncAPI documents from your terminal, then publish them to Scalar.

npx @scalar/cli document validate openapi.yaml

Documentation · Command reference · CI and scripting · Discord

Common tasks

Every example works with npx @scalar/cli in place of scalar if you have not installed the CLI.

Validate and lint an API description

scalar document validate openapi.yaml
scalar document lint openapi.yaml
scalar document lint openapi.yaml --rule .spectral.yaml

validate checks the document against the OpenAPI or AsyncAPI specification. lint applies Spectral rules and fails only on errors. Lint reports and baselines →

Bundle split files into one

scalar document bundle openapi.yaml --output openapi.bundled.yaml
scalar document bundle openapi.yaml --output openapi.bundled.yaml --treeShake

Pulls every external $ref into a single file. --treeShake drops components nothing uses. The input can be a URL.

Preview the API reference

scalar document serve openapi.yaml --watch

Serves an interactive API reference that reloads as you edit. Pass --config reference.json for API Reference options.

Mock the API

scalar document mock openapi.yaml --watch

Starts a mock server that answers with the examples and schemas in your document, so you can try requests before the API exists.

Upgrade and convert

scalar document upgrade swagger.json --output openapi.json
scalar document convert postman-collection.json --output openapi.json

Upgrades Swagger 2.0 and OpenAPI 3.0 to OpenAPI 3.1, and converts Postman collections to OpenAPI.

Publish to Scalar

scalar auth login
scalar registry publish openapi.yaml --namespace acme --slug my-api --version 1.0.0
scalar project preview
scalar project publish --slug my-docs

Push API descriptions to the Scalar Registry, 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.

Install

Standalone binary, no Node.js required:

# macOS and Linux
curl -fsSL https://cdn.scalar.com/cli/install.sh | bash

# Windows (PowerShell)
irm https://cdn.scalar.com/cli/install.ps1 | iex

Or with npm:

npm install --global @scalar/cli

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 covers upgrades and shell completion.

Use with AI agents

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:

scalar context

The package also ships an Agent Skill at skills/scalar-cli/SKILL.md. Copy it into your project:

mkdir -p .claude/skills
cp -r "$(npm root -g)/@scalar/cli/skills/scalar-cli" .claude/skills/

Use in CI

# .github/workflows/openapi.yml
name: OpenAPI
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - run: npx --yes @scalar/cli document lint openapi.yaml --format github-actions

--format github-actions turns findings into annotations on the pull request. JSON output, JUnit reports, and lint baselines →

Commands

| Command | Description | Subcommands | | --- | --- | --- | | scalar auth | Log in to Scalar and manage your session | login, whoami, logout | | scalar access-group | Manage access groups and allowed email domains for the current team | list, create, get, update, delete, domain add, domain remove | | scalar document | Work with OpenAPI and AsyncAPI descriptions | bundle, split, join, format, convert, markdown, mock, serve, share, validate, void, lint, upgrade | | scalar project | Manage Scalar Docs projects | list, get, init, check-config, create, preview, publish, rollback, deployments list, upgrade | | scalar registry | Manage API descriptions in the Scalar Registry | publish, update, delete, list, get | | scalar team | List and switch between your Scalar teams | list, get, set | | scalar sdk | Manage Scalar SDKs (Enterprise only) | list, get, create, update, delete, build | | scalar schema | Manage shared schemas in the Scalar Registry | delete, update, list, get, publish | | scalar readme | Open CLI documentation in your browser | generate | | scalar upgrade | Upgrade the Scalar CLI to the latest version | | | scalar context | Print every command, argument, and option as JSON for AI agents | | | scalar completion | Generate shell completion definitions | |

Run scalar <command> --help for options, or see the command reference.

Authentication details

Run scalar auth whoami to show your email, current team name and ID, role, and authentication method (browser session or personal token). Use scalar auth whoami --json for structured output with email, team: { uid, name }, role, and authentication (browser_session or personal_token). If the team name cannot be loaded, the team ID remains available and JSON returns null for the name. Missing email or role values also return null. Credentials are never included.