spectral "command not found" (CLI not installed) in CI

By Kaveh Alemi·Latchkey

The shell could not find the spectral executable because the Spectral CLI package is not installed on the runner. It is an npm package and is not preinstalled.

What this error means

A step calling spectral lint ... fails with "spectral: command not found" and the job exits with code 127.

/home/runner/work/_temp/script.sh: line 1: spectral: command not found
Error: Process completed with exit code 127.

Common causes

The Spectral CLI is not installed

Without an explicit npm install -g @stoplight/spectral-cli, the spectral binary is absent from the runner PATH.

A local install is not on PATH

A project-local install lives under node_modules/.bin, which is not on PATH unless invoked through npx or a package script.

How to fix it

Install the Spectral CLI, then lint

1. Install @stoplight/spectral-cli globally with npm.
2. Run spectral lint against your spec.
3. Pin the CLI version for reproducibility.

- run: npm install -g @stoplight/spectral-cli
- run: spectral lint openapi.yaml

Run through npx without a global install

npx fetches and runs the Spectral CLI on demand.

npx @stoplight/spectral-cli lint openapi.yaml

How to prevent it

• Install @stoplight/spectral-cli explicitly before the lint step.
• Prefer npx @stoplight/spectral-cli to avoid a global install.
• Pin the CLI version so lint results are reproducible.

Frequently asked questions

Related guides

References

• GitHub Actions documentation