CLI

This guide will help you interact with our registry with our CLI, programmatically. If you want to also work with the registry with our dashboard you can.

Before running any of the commands below, make sure you are authenticated with the Scalar CLI using your API key.

Publishing API Documents

To add an API document to the registry, use the publish command:

scalar registry publish ./openapi.yaml --namespace your-team --slug your-api

publish accepts OpenAPI and AsyncAPI documents alike. The format is detected when the document reaches the registry, so the command is the same either way:

scalar registry publish ./asyncapi.yaml --namespace your-team --slug your-events-api

Required Parameters

file: Path to your API document
--namespace: Your Scalar team namespace
--slug: Unique identifier for the registry entry (defaults to title if not specified)

Optional Parameters

--version: API version (e.g., 0.1.0)
--private: Make API private (default: false)
--force: Force override an existing version (default: false)

Examples

# Basic publish
scalar registry publish api/openapi.json --namespace your-team --slug user-api

# Publish with version and make private
scalar registry publish api/openapi.json --namespace your-team --slug user-api --version 1.0.0 --private

# Force update existing version
scalar registry publish api/openapi.json --namespace your-team --slug user-api --force

Managing Registry Documents

List Documents

View all registry APIs for your team:

scalar registry list --namespace your-team

Update Document Metadata

Update title and description without re-uploading the file:

scalar registry update your-team your-api --title "New Title" --description "New description"

Delete Documents

Remove a document from the registry:

scalar registry delete your-team your-api

Validation and Quality

Before publishing, you can validate your API document:

scalar document validate ./openapi.yaml

You can also lint your document using Spectral rules:

scalar document lint ./openapi.yaml

And use Rules from the Registry:

scalar document lint ./openapi.yaml --rule https://registry.scalar.com/@your-team/rules/your-rule

We do not currently support AsyncAPI for validate and lint. validate checks your document against the OpenAPI specification, and lint runs the spectral:oas ruleset, so pointing either one at an AsyncAPI document reports errors that do not apply to it. Publishing an AsyncAPI document to the registry works as normal.

Need it? Tell us on GitHub or email support@scalar.com.

Team Management

If you're part of multiple teams, you can manage which team is active:

# List all teams you're part of
scalar team list

# Set active team
scalar team set --team team-uid

Working with Multiple APIs

For repositories containing multiple APIs, you can use the CLI in scripts or CI/CD pipelines:

# Example: Publish multiple APIs
scalar registry publish ./apis/user-api/openapi.json --namespace your-team --slug user-api
scalar registry publish ./apis/product-api/openapi.json --namespace your-team --slug product-api
scalar registry publish ./apis/order-api/openapi.json --namespace your-team --slug order-api

Integration with CI/CD

For automated publishing, you can integrate the CLI with GitHub Actions or other CI/CD systems. See our GitHub Actions guide for detailed examples.

The CLI supports environment variables and can be easily integrated into automated workflows for continuous deployment of your API documentation.

Rules

GitHub Actions