CLI

Deployment modes#

scalar project publish supports two ways to deploy:

• Default: The CLI uploads your project configuration and content from your local machine to Scalar. What you have on disk is what gets deployed.
• With --github: Use only when your Docs project is connected to a GitHub repository. Scalar pulls the files from GitHub and deploys that. Local changes are ignored. Use this to trigger a deploy from the linked repository.

Installation#

Install the Scalar CLI globally or use it via npx:

npm install -g @scalar/cli

Or use npx without installation:

npx @scalar/cli project publish

Authentication#

Authenticate with the Scalar platform before publishing:

scalar auth login

You can login with email and password, or use a personal token:

scalar auth login --email your@email.com --password yourpassword
scalar auth login --token your-personal-token

Verify your current authentication status:

scalar auth whoami

Project Setup#

Initialize Configuration#

Create a scalar.config.json file in your project root:

scalar project init

This command prompts for a subdomain and creates the configuration file.

Create Project#

Create a new project on the Scalar platform:

scalar project create --name "My Documentation" --slug your-docs

Local Preview#

Preview your documentation locally before publishing:

scalar project preview

Preview Deployments#

Publish in preview mode (e.g. for pull requests) without going live:

scalar project publish --slug your-docs --preview

Publishing#

Publish from local files#

Publish your project by uploading it directly from your machine:

scalar project publish

Specify a project slug and config file:

scalar project publish --slug your-docs --config scalar.config.json

Publish from GitHub#

If your project is connected to a GitHub repository, you can deploy from the remote repo instead. Scalar pulls the files from GitHub; local changes are ignored.

scalar project publish --github

Options#

Use project publish for ad-hoc or local-first workflows. Use project publish --github when the project is connected to GitHub and you want the deployment to reflect the remote repository.

Your documentation will be available at https://your-subdomain.apidocumentation.com.

Rollback#

If a deployment introduced a problem, you can roll the live deployment back to a previously deployed build. List recent production deployments to find the build you want, then roll back to the previous build (or pass --to <build-id> to target a specific one).

# See recent production deployments
scalar project deployments list --slug your-docs
 
# Roll back to the previous build (or pass --to <build-id>)
scalar project rollback --slug your-docs