#The stylelint CLI

#Installation

stylelint is an npm package. Install it using:

npm install -g stylelint

#Usage

stylelint --help prints the CLI documentation.

The CLI outputs formatted results into process.stdout, which you can read with your human eyes or pipe elsewhere (e.g. write the information to a file).

#Examples

When you run commands similar to the examples below, be sure to include the quotation marks around file globs. This ensures that you can use the powers of node-glob (like the ** globstar) regardless of your shell.

Looking for .stylelintrc and linting all .css files in the foo directory:

stylelint "foo/*.css"

Looking for .stylelintrc and linting stdin:

echo "a { color: pink; }" | stylelint

Using bar/mySpecialConfig.json as config to lint all .css files in the foo directory, then writing the output to myTestReport.txt:

stylelint "foo/*.css" --config bar/mySpecialConfig.json > myTestReport.txt

Using bar/mySpecialConfig.json as config, with quiet mode on, to lint all .css files in the foo directory and any of its subdirectories and also all .css files in the bar directory, then writing the JSON-formatted output to myJsonReport.json:

stylelint "foo/**/*.css bar/*.css" -q -f json --config bar/mySpecialConfig.json > myJsonReport.json

Caching processed .scss files in order to operate only on changed ones in the foo directory, using the cache and cache-location options:

stylelint "foo/**/*.scss" --cache --cache-location "/Users/user/.stylelintcache/"

Linting all the .scss files in the foo directory, using the syntax option:

stylelint "foo/**/*.scss" --syntax scss

Linting all .css files except those within docker subfolders, using negation in the input glob:

stylelint "**/*.css, !**/docker/**"

In addition to --syntax scss, stylelint supports --syntax less and --syntax sugarss by default. If you're using one of the default syntaxes, you may not need to provide a --syntax option: non-standard syntaxes can be automatically inferred from the following file extensions: .less, .scss, and .sss.

Additionally, stylelint can accept a custom PostCSS-compatible syntax. To use a custom syntax, supply a syntax module name or path to the syntax file: --custom-syntax custom-syntax or --custom-syntax ./path/to/custom-syntax.

Note, however, that stylelint can provide no guarantee that core rules will work with syntaxes other than the defaults listed above.

#Recursively linting a directory

To recursively lint a directory, using the ** globstar:

stylelint "foo/**/*.scss"

The quotation marks around the glob are important because they will allow stylelint to interpret the glob, using node-glob, instead of your shell, which might not support all the same features.

#Autofixing errors

With --fix option stylelint will fix as many errors as possible. The fixes are made to the actual source files. All unfixed errors will be reported.

Linting all .css files in the foo directory. And fixing source files if violated rules support autofixing:

stylelint "foo/*.css" --fix

Note: It's an experimental feature. It currently does not respect special comments for disabling stylelint within sources (e. g. /* stylelint-disable /*). Autofixing will be applied regardless of these comments.

If you're using both these special comments and autofixing, please run stylelint twice as a temporary solution. On the first run, some violations could be missed, or some violations might be reported incorrectly.

#Syntax errors

The CLI informs you about syntax errors in your CSS. It uses the same format as it uses for linting violations. The error name is CssSyntaxError.

#Exit codes

The CLI can exit the process with the following exit codes:

  • 1: Something unknown went wrong.
  • 2: At least one rule with an "error"-level severity triggered at least one violations.
  • 78: There was some problem with the configuration file.
  • 80: A file glob was passed, but it found no files.