# OpenLint CLI [Once OpenLint is installed](../getting-started/installation.mdx) and [you have a ruleset](../../README.md#installation-and-usage), run the `openlint` command-line: ```bash openlint lint openlint.yaml ``` Use this command to lint with a custom ruleset or one that's located in a different directory than your API document: ```bash openlint lint openlint.yaml --ruleset myruleset.json ``` You can lint multiple files at the same time by passing on multiple arguments: ```bash openlint lint openlint.yaml https://example.com/openlint/openapi.json https://example.com/train-travel/openapi.yaml ``` Alternatively, you can use [glob syntax](https://github.com/mrmlnc/fast-glob#basic-syntax) to match multiple files at once: ```bash 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." 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](../getting-started/rulesets.md), or extend and modify the core rulesets: - [OpenAPI ruleset](../reference/openapi-rules.md) - [AsyncAPI ruleset](../reference/asyncapi-rules.md) - [Arazzo ruleset](../reference/arazzo-rules.md) ## 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: ```yaml json_schema type: array items: 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 ``` ```json [ { "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. ```bash openlint lint "specs/**/*.yaml" -f json -f junit -o.json results.json -o.junit junit.xml ``` You can also pipe an output to stdout. ```bash openlint lint "specs/**/*.yaml" -f stylish -f junit -o.junit junit.xml -o.stylish "" ``` It's possible to output each format to stdout. ```bash openlint lint "specs/**/*.yaml" -f text -f stylish -o.text "" -o.stylish "" ``` ## Proxying To have requests made from Spectral be proxied through a server, you'd need to specify the `PROXY` environment variable: `PROXY=<> 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`. ```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](./javascript.mdx#using-a-custom-resolver).