Scalar CLI

Scalar CLI brings fast OpenAPI parsing and bundling to your terminal. Validate API descriptions, bundle files, lint with Spectral rules, and preview interactive API documentation with one actively maintained toolkit.

Start with the scalar document commands for your local OpenAPI workflow, then use the same CLI to publish documentation and manage APIs on the Scalar platform.

Quick Start

Run commands without a global installation. Replace openapi.yaml with the path to your API description:

# Check that your API description is valid
npx @scalar/cli document validate openapi.yaml

# Bundle external references into a single file
npx @scalar/cli document bundle openapi.yaml --output openapi.bundled.yaml

# Preview interactive API documentation
npx @scalar/cli document serve openapi.bundled.yaml

Work with OpenAPI Documents

Bundle files and references

Keep your API description organized across multiple files while sharing a single bundled file with documentation tools and SDK generators. Bundling pulls external $ref values into one API description.

npx @scalar/cli document bundle openapi.yaml --output openapi.bundled.yaml

Add --treeShake to remove unused components from the output:

npx @scalar/cli document bundle openapi.yaml --output openapi.bundled.yaml --treeShake

The input can also be a URL. See the bundle options for controlling concurrent fetches and generating a map of resolved URLs.

Validate and lint

Validate your API description against the OpenAPI Specification:

npx @scalar/cli document validate openapi.yaml

Use linting to check style and design conventions with Spectral rules:

npx @scalar/cli document lint openapi.yaml

To use your own ruleset, pass its file path or URL with --rule:

npx @scalar/cli document lint openapi.yaml --rule .spectral.yaml

Preview documentation and mock your API

Serve an interactive API Reference and watch your local file for changes:

npx @scalar/cli document serve openapi.yaml --watch

Start a mock server from the same API description to try requests before your API is ready:

npx @scalar/cli document mock openapi.yaml --watch

More document commands

Explore all document commands or get help with a specific command:

npx @scalar/cli document --help
npx @scalar/cli document bundle --help

Installation

Standalone CLI

Install the latest release without Node.js, npm, or administrator access.

macOS and Linux:

curl -fsSL https://cdn.scalar.com/cli/install.sh | bash

Windows (PowerShell):

irm https://cdn.scalar.com/cli/install.ps1 | iex

The installers pick 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. Re-run the installer to upgrade.

npm

If you already use Node.js, install the CLI globally:

npm install --global @scalar/cli

You can then use scalar in place of npx @scalar/cli in the examples above:

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

Conflict: EXIST: file already exists

Git ships its own, unrelated scalar executable. If you never use it, replace it:

npm -g --force install @scalar/cli

To keep Git's scalar, use the scalar-cli alias that npm installs, or run the CLI without installing it:

npx @scalar/cli help
pnpm dlx @scalar/cli help

Shell completion

Completion for Bash, Zsh, and Fish runs locally and covers commands, flags, and option values.

# Bash: then add the `source` line to ~/.bashrc
mkdir -p ~/.local/share/scalar
scalar completion bash > ~/.local/share/scalar/completion.bash
source ~/.local/share/scalar/completion.bash

# Zsh: then add `fpath=(~/.zsh/completions $fpath)` before `compinit` in ~/.zshrc
mkdir -p ~/.zsh/completions
scalar completion zsh > ~/.zsh/completions/_scalar

# Fish
mkdir -p ~/.config/fish/completions
scalar completion fish > ~/.config/fish/completions/scalar.fish

Completion reads the installed CLI on each Tab press, so new commands appear after an upgrade. Regenerate the script after upgrading to pick up changes to the shell adapter itself.

AI agents

scalar context prints every command, argument, option, default, and choice as JSON, plus notes on running the CLI without prompts. Point an agent at it instead of having it scrape --help:

scalar context

The CLI also ships an Agent Skill at skills/scalar-cli/SKILL.md. Copy it into your agent's skills directory:

mkdir -p .claude/skills

# npm (global install)
cp -r "$(npm root -g)/@scalar/cli/skills/scalar-cli" .claude/skills/

# Standalone CLI on macOS or Linux
cp -r "$(dirname "$(readlink "$(command -v scalar)")")/app/skills/scalar-cli" .claude/skills/

On Windows, the standalone CLI keeps the skill in %LOCALAPPDATA%\Scalar\current\app\skills\scalar-cli.

Commands

The command reference lists every command and option.

Authentication

To use the CLI with Scalar services, see the Authentication guide.

GitHub Actions

To validate and bundle your API description on pushes and pull requests, 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@v6
      - name: Use Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
      - name: Validate OpenAPI File
        # Replace `docs/openapi.yaml` with the path to your API description.
        run: npx --yes @scalar/cli document validate docs/openapi.yaml
      - name: Bundle OpenAPI File
        run: npx --yes @scalar/cli document bundle docs/openapi.yaml --output openapi.bundled.yaml

For lint reports, baselines, and JSON output in pipelines, see CI and scripting.