Once OpenLint is installed and you have a ruleset, run the openlint command-line:
openlint lint openlint.yamlUse this command to lint with a custom ruleset or one that’s located in a different directory than your API document:
openlint lint openlint.yaml --ruleset myruleset.jsonYou can lint multiple files at the same time by passing on multiple arguments:
openlint lint openlint.yaml https://example.com/openlint/openapi.json https://example.com/train-travel/openapi.yamlAlternatively, you can use glob syntax to match multiple files at once:
openlint lint ./reference/**/*.oas*.{json,yml,yaml}Other options include:
--version Show version number [boolean] --help Show help [boolean] -e, --encoding text encoding to use [string] [choices: "utf8", "ascii", "utf-8", "utf16le", "ucs2", "ucs-2", "base64", "latin1"] [default: "utf8"] -f, --format formatters to use for outputting results, more than one can be provided by using multiple flags [string] [choices: "json", "stylish", "junit", "html", "text", "teamcity", "pretty", "github-actions", "sarif", "code-climate", "gitlab", "markdown"] [default: "stylish"] -o, --output where to output results, can be a single file name, multiple "output.<format>" or missing to print to stdout [string] --stdin-filepath path to a file to pretend that stdin comes from [string] --resolver path to custom json-ref-resolver instance [string] -r, --ruleset path/URL to a ruleset file [string] -F, --fail-severity results of this level or above will trigger a failure exit code [string] [choices: "error", "warn", "info", "hint"] [default: "error"] -D, --display-only-failures only output results equal to or greater than --fail-severity [boolean] [default: false] --ignore-unknown-format do not warn about unmatched formats [boolean] [default: false] --fail-on-unmatched-globs fail on unmatched glob patterns [boolean] [default: false] --show-documentation-url show documentation url in output result [boolean] [default: false] -v, --verbose increase verbosity [boolean] -q, --quiet no logging - output only [boolean]OpenLint CLI supports loading documents as YAML or JSON, and validation of OpenAPI v3.2-v2.0 documents via the built-in ruleset.
Using a Ruleset File
If you don’t specify a ruleset file with the --ruleset parameter, the OpenLint CLI looks for a ruleset file with any of the following names in the current working directory.
.openlint.yml.openlint.yaml.openlint.json.openlint.js.spectral.yml.spectral.yaml.spectral.json.spectral.js
Spectral won’t lint the document if no ruleset is specified and no default ruleset file is found.
Here you can build a custom ruleset, or extend and modify the core rulesets:
Error Results
Spectral has a few different error severities: error, warn, info, and hint, and they’re in order from highest to lowest. By default, all results are shown regardless of severity, but since v5.0, only the presence of errors causes a failure status code of 1. Seeing results and getting a failure code for it are now two different things.
The default behavior can be modified with the --fail-severity= option. Setting fail severity to --fail-severity=info returns a failure status code of 1 for any info results or higher. Using --fail-severity=warn causes a failure status code for errors or warnings.
Changing the fail severity wont’ affect output. To change the results Spectral CLI prints to the screen, add the --display-only-failures switch (or just -D for short). This removes any results which are below the specified fail severity.
Formatters
The github-actions formatter was introduced in Spectral v6.10.0. If you are using an older release, upgrade the CLI before using -f github-actions.
JSON Formatter
Spectral’s JSON formatter outputs the results of a Spectral analysis in a JSON format that is easily parsable and human-readable. The output can be used to programmatically access and process the results of the analysis. You can enable this by adding -f json --quiet to the cli command.
Here’s the schema for the output:
type: arrayitems: type: object properties: code: type: string description: A string that represents the rule code that has been violated or triggered in OpenLint. This code is unique to each rule defined in OpenLint. path: type: array description: An array of strings that indicate the location within the analyzed document where the rule was triggered. It shows the "path" in the document structure to the issue. items: type: string message: type: string description: A string that contains a human-readable message describing the issue found by OpenLint. This message typically provides information on why the rule was triggered and how to fix the issue. severity: enum: - 0 - 1 - 2 - 3 description: An integer representing the severity level of the rule violation. The severity levels usually follow a specific scale defined by OpenLint. 0 equals error, while 3 is hint. range: type: object description: An object that describes where in the file the issue was found. It contains two sub-properties, start and end, each of which is an object with line and character properties. line and character are integers that represent the line number and the character position within the line, respectively, where the issue starts or ends. All the values are zero indexed. properties: start: type: object properties: line: type: integer minimum: 0 character: type: integer minimum: 0 required: - line - character end: type: object properties: line: type: integer minimum: 0 character: type: integer minimum: 0 required: - line - character source: type: string description: A string that contains the file path of the document that was analyzed by Spectral. It points to the source of the issue. required: - code - path - message - severity - range - source
[ { "code": "invalid-response", "path": ["paths", "/users/{id}", "get", "responses", "200"], "message": "The '200' response should include a schema definition.", "severity": 2, "range": { "start": { "line": 32, "character": 12 }, "end": { "line": 35, "character": 14 } }, "source": "/Users/johndoe/projects/api-definition/openapi.yaml" }]Multiple formatters
If you wish to output results in multiple formats, you can do so by passing multiple -f flags.
In order to output results in multiple formats, you must also pass the -o flag with a filename for each format.
openlint lint "specs/**/*.yaml" -f json -f junit -o.json results.json -o.junit junit.xmlYou can also pipe an output to stdout.
openlint lint "specs/**/*.yaml" -f stylish -f junit -o.junit junit.xml -o.stylish "<stdout>"It’s possible to output each format to stdout.
openlint lint "specs/**/*.yaml" -f text -f stylish -o.text "<stdout>" -o.stylish "<stdout>"Proxying
To have requests made from Spectral be proxied through a server, you’d need to specify the PROXY environment variable:
PROXY=<<PROXY_SERVER_ADDRESS>> openlint lint spec.yaml
Custom $ref Resolving
To customize $ref resolving, use the --resolver flag and pass a path to the JS file exporting a custom instance of json-ref-resolver Resolver.
Example
Assuming the filename is called my-resolver.js and the content looks as follows, the path should look like: --resolver=./my-resolver.js.
const { Resolver } = require("@stoplight/json-ref-resolver");
module.exports = new Resolver({ resolvers: { // pass any resolver for the protocol you need },});You can learn more about $ref resolving in the JS section.
Last updated Oct 24, 2026