Command-Line Usage

The coffeelint command is the most common way to run CoffeeLint. This page documents every option, how files are selected, how configuration is chosen, and what the exit codes mean.

Synopsis

Usage: coffeelint [options] source [...]

Each source can be a file or a directory. Run coffeelint with no sources (and without --stdin) to print the help text; in that case the process exits with status 1.

Options Reference

Option Alias Description
--file <path> -f Use the given configuration file for all linted files. Accepts a coffeelint.json or a package.json (its coffeelintConfig section is used).
--noconfig Ignore all configuration: no -f file, no discovered files. Built-in defaults are used.
--rules <module> Load a custom rule (or an array of rules) from an npm module or a file path.
--reporter <name> Output format: default, csv, jslint, checkstyle, raw, or the name/path of a custom reporter module.
--color=<when> Colorize output: always, never, or auto (colorize only when stdout is a terminal). Default: auto.
--quiet -q Only report error-level problems; hide warnings.
--stdin -s Lint CoffeeScript read from standard input.
--literate With --stdin, treat the input as Literate CoffeeScript.
--ext <list> Additional file extensions to collect from directories, comma-separated (for example litcoffee,cjsx).
--cache -c Cache lint results between runs.
--makeconfig Print the full default configuration as JSON and exit.
--trimconfig Print the minimal configuration equivalent to your current one and exit.
--version -v Print the CoffeeLint version and exit.
--help -h Print help and exit.
-r Accepted for backward compatibility; has no effect (directories are always searched recursively).

Deprecated Options

Option Replacement
--csv --reporter csv
--jslint --reporter jslint
--checkstyle --reporter checkstyle
--nocolor --color=never

The deprecated reporter flags still work, but because their output is usually consumed by other programs, CoffeeLint cannot simply print a warning to the terminal. Instead it injects a warning-level entry for a fake file named coffeelint_fake_file.coffee into the report, with the message parameter --csv is deprecated. Use --reporter csv instead (or the equivalent for the flag you used). Switch to --reporter to get rid of it.

Selecting Files

Files and Directories

  • A file passed on the command line is always linted, whatever its extension.
  • A directory is searched recursively for *.coffee files. Anything under node_modules is skipped.
  • Paths are normalized, so ./src/app.coffee is reported as src/app.coffee.
coffeelint src test bin/server.coffee

Additional Extensions

Only .coffee files are collected from directories by default. Literate files (.litcoffee, .coffee.md) and custom extensions must be requested with --ext:

coffeelint --ext litcoffee,cjsx src

The coffee extension is always included in addition to the ones you list.

Note: Whether a file is treated as Literate CoffeeScript is decided by its name (.litcoffee or .coffee.md), not by --literate. The --literate flag only applies to --stdin.

Ignoring Files with .coffeelintignore

If a file named .coffeelintignore exists in the current working directory, its patterns are applied to the collected file list. The file uses .gitignore-style syntax (it is parsed with the ignore package). CoffeeLint's own repository uses:

node_modules
test/fixtures

Patterns are matched against the normalized paths (for example test/fixtures/x.coffee), so run CoffeeLint from the directory that contains .coffeelintignore, typically the project root. The ignore file is not consulted in --stdin mode.

Linting Standard Input

Use --stdin to lint code piped from another program or from an editor buffer:

cat src/app.coffee | coffeelint --stdin

The report names the input stdin. Literate CoffeeScript needs the extra flag:

cat README.litcoffee | coffeelint --stdin --literate

When no -f file is given, configuration is discovered starting from the current working directory, exactly as it would be for a file located there.

Choosing Configuration

CoffeeLint picks the configuration as follows:

  1. --noconfig disables all configuration, including -f. Defaults apply.
  2. -f <path> uses one file for everything being linted.
  3. Otherwise, configuration is discovered separately for each linted file, starting from that file's directory: the COFFEELINT_CONFIG environment variable, then the nearest package.json with a coffeelintConfig section, then the nearest coffeelint.json, then coffeelint.json in your home directory.

The full rules, including extends and module resolution, are in Configuration.

# Use a specific file
coffeelint -f config/coffeelint.json src

# Use the coffeelintConfig section of a package.json
coffeelint -f package.json src

# Use a config from an environment variable
COFFEELINT_CONFIG=/etc/coffeelint.json coffeelint src

Configuration files may contain JavaScript-style comments; they are stripped before parsing.

Generating and Trimming Configuration

--makeconfig prints every built-in rule with its default settings (rule names, messages, and descriptions are omitted):

coffeelint --makeconfig > coffeelint.json

--trimconfig loads your configuration (from -f, or discovered from the current directory), compares it with the defaults, and prints only what differs:

coffeelint -f coffeelint.json --trimconfig

Details worth knowing:

  • If you trim a file that equals the defaults, the output is {}.
  • A rule set to ignore that is also ignored by default is dropped entirely; a rule you set to ignore that is normally active is reduced to { "level": "ignore" }.
  • Rule names that CoffeeLint does not recognize are dropped, which makes --trimconfig a handy way to spot typos in rule names.
  • When trimming a file passed with -f, the output reuses that file's indentation width (detected from its second line).

Reporters and Output

The default reporter prints a human-readable report. Pick another with --reporter:

coffeelint --reporter csv src
coffeelint --reporter jslint src > jslint.xml
coffeelint --reporter checkstyle src > checkstyle.xml
coffeelint --reporter raw src > lint.json

A value that is not a built-in reporter name is resolved as a module from the current directory (with .js, .coffee, .litcoffee, and .coffee.md extensions), falling back to a plain require:

coffeelint --reporter ./tools/my-reporter.coffee src

See Reporters for sample output of each format and how to write your own.

Quiet Mode

-q hides warnings in every built-in reporter. With the default reporter, nothing at all is printed if there are no errors, which keeps CI logs short:

coffeelint -q src

Colors

By default, colors are used only when standard output is a terminal. Force them on or off with --color=always or --color=never.

Loading Custom Rules

--rules loads a rule module before linting:

coffeelint --rules coffeelint-my-rule src
coffeelint --rules ./lint-rules/no_forbidden_names.coffee src

The argument is resolved as a project-local module first, then as a global module, then as a path relative to the current directory. The module can export a single rule class or an array of rule classes. Rules loaded this way use the default level declared in the rule unless your configuration overrides it. See Writing Custom Rules.

Caching

-c (--cache) stores results in a coffeelint folder inside the operating system's temporary directory. Each entry is keyed by:

  • the CoffeeScript version,
  • the CoffeeLint version,
  • a hash of the configuration in effect,
  • a hash of the file's source.

Unchanged files linted with the same configuration and versions are served from the cache. Changing the configuration automatically invalidates old entries because the configuration hash changes. To clear the cache, delete that temporary folder.

Exit Codes

Exit code Meaning
0 No error-level problems (warnings may exist), or --version, --help, --makeconfig, --trimconfig completed.
1 At least one error-level problem was found (including CoffeeScript syntax errors via coffeescript_error), or no sources were given.

An uncaught exception (for example a malformed -f file or a custom rule that fails to load) also terminates the process with a non-zero status.

Common Recipes

# Lint the whole project, errors only, no colors (CI logs)
coffeelint -q --color=never .

# Lint with a strict CI config but a relaxed local one
coffeelint -f coffeelint.ci.json src

# Lint Literate CoffeeScript alongside regular files
coffeelint --ext litcoffee docs src

# Lint an editor buffer
coffeelint --stdin < src/app.coffee

# Speed up repeated runs on a big codebase
coffeelint --cache src

See Also