Spotlight CLI

Spotlight is a flexible JSON/YAML linter for API descriptions, with out-of-the-box support for OpenAPI v2/v3.x, AsyncAPI, and Arazzo, plus fully custom rulesets for your own API style guides.

It is part of Spotlight Rules — an openly-governed, well-maintained build of the linter under API Commons — alongside spotlight-spec (the standalone ruleset specification) and spotlight-vscode (the editor extension).

Provenance. Spotlight CLI originated as a fork of Stoplight Spectral (Apache 2.0) and is released as an independent 1.0 under API Commons. Built-in rulesets are referenced with the spotlight: aliases (spotlight:oas, spotlight:asyncapi, spotlight:arazzo) and rulesets are discovered from .spotlight.* files. See FORK.md for attribution and changes.

Features

• Custom rulesets — write rules to lint any JSON or YAML document.
• Ready-to-use rulesets — validate OpenAPI v2 & v3.x, AsyncAPI, and Arazzo v1.
• API style guides — enforce consistency across all your APIs.
• Built-in functions — pattern checks, casing, length, enumerations, and more.
• Custom functions — write your own for advanced cases.

Installation

npm install -g @spotlight-rules/spotlight-cli
# or
yarn global add @spotlight-rules/spotlight-cli

This installs the spotlight command.

Usage

1. Create a ruleset

Spotlight needs a ruleset to lint files. A ruleset is a JSON, YAML, or JavaScript file (commonly .spotlight.yaml) containing a collection of rules. To start from the built-in rulesets:

echo 'extends: ["spotlight:oas", "spotlight:asyncapi", "spotlight:arazzo"]' > .spotlight.yaml

The ruleset format is documented in spotlight-spec.

2. Lint

# ruleset auto-discovered in the working directory
spotlight lint myapi.yaml

# or point at a specific ruleset
spotlight lint myapi.yaml --ruleset myruleset.yaml

Documentation

Guides and reference live in docs/:

• Getting started
• Rulesets · Custom rulesets · Custom functions
• Using the CLI · JavaScript API · Continuous integration

The ruleset format is specified independently in spotlight-spec, with a JSON Schema you can use for validation and editor autocomplete.

Support

Questions, bugs, and feature requests: open an issue.

Contributing

See CONTRIBUTING.md.

Credits

Spotlight CLI builds on the excellent work of Stoplight and the Spectral contributors, whose Apache-2.0 project it forks. The ruleset format, built-in rulesets, and much of this codebase originate there — see FORK.md and NOTICE for full attribution.

License

Apache License 2.0 — see LICENSE.

---

Part of Spotlight Rules — a project of API Evangelist, maintained openly under API Commons.