CLI Options Reference

This page lists all command line parameters, options, and exit codes supported by markdownlint-cli.

Syntax

markdownlint [options] [files|directories|globs...]

If you execute the command with no arguments, the CLI displays the help guide and exits.

Command-Line Arguments Reference

Option Description Default / Details
-V, --version Outputs the current application version number and exits. Matches package version (e.g., 0.47.0).
-c, --config <configFile> Path to your configuration file (JSON, JSONC, JS, CJS, YAML, or TOML). Falls back to auto-discovering files if omitted.
--configPointer <pointer> Points to a nested sub-object inside your configuration file using JSON Pointer (RFC 6901) paths. "" (targets the root configuration object).
-d, --dot Includes files and folders starting with a dot (such as .github/) in scans. Excluded by default.
-f, --fix Applies fixes for rules supporting automatic formatting corrections directly to your files. Modifies files on disk in-place. Does not support STDIN inputs.
-i, --ignore <pattern> Excludes files, directories, or globs from checks. Can be specified multiple times to define multiple ignore paths. Excluded target array: []
-j, --json Outputs style violations as a JSON array instead of human-readable line logs. Emits parsable logs to standard error (STDERR).
-o, --output <file> Saves formatting reports directly to a file instead of writing to standard error. Prints to standard error if omitted.
-p, --ignore-path <file> Specifies a custom file containing ignore patterns. Defaults to .markdownlintignore in the working directory.
-q, --quiet Suppresses warning and error output logs from standard streams. The CLI still returns a non-zero exit code if violations exist.
-r, --rules <path> Loads custom rule modules. Can point to single JavaScript files, whole directories, glob strings, or NPM package dependencies. Loaded custom rule array: []
-s, --stdin Reads and processes Markdown content directly from standard input (STDIN). Cannot be combined with file path inputs or --fix.
--enable <rules...> Explicitly overrides settings files to enable specific rules. Variadic argument; requires the -- separator.
--disable <rules...> Explicitly overrides settings files to disable specific rules. Variadic argument; requires the -- separator.
-h, --help Displays the command-line help menu.

The POSIX -- Parameter Separator

Because the --enable and --disable options are variadic (they accept a space-separated list of multiple rules), the terminal parser evaluates all following strings as part of that list.

To tell the parser that your list of rules has ended and subsequent arguments are file paths, you must insert a double dash separator (--) before defining your target files.

Incorrect Command Example:

# This fails: the parser interprets the file path 'README.md' as another rule name to disable
markdownlint --disable MD013 MD033 README.md

Correct Command Example:

# Correct: The parser separates the disabled rules list from the target file arguments
markdownlint --disable MD013 MD033 -- README.md

Parsing Structured JSON Outputs (--json)

If you compile formatting errors as part of an automated pipeline, run checks with the --json option. This outputs a structured JSON array directly to standard error (STDERR), making it easy to parse dynamically.

Execute with JSON output:

markdownlint --config warning-config.json incorrect.md --json

Sample JSON Array Result:

[
  {
    "fileName": "incorrect.md",
    "lineNumber": 1,
    "ruleNames": ["MD041", "first-line-heading", "first-line-h1"],
    "ruleDescription": "First line in a file should be a top-level heading",
    "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/Rules.md#md041",
    "errorDetail": null,
    "errorContext": "## header 2",
    "errorRange": null,
    "fixInfo": null,
    "severity": "warning"
  },
  {
    "fileName": "incorrect.md",
    "lineNumber": 1,
    "ruleNames": ["MD022", "blanks-around-headings"],
    "ruleDescription": "Headings should be surrounded by blank lines",
    "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/Rules.md#md022",
    "errorDetail": "Expected: 1; Actual: 0; Below",
    "errorContext": "## header 2",
    "errorRange": null,
    "fixInfo": {
      "lineNumber": 2,
      "insertText": "\n"
    },
    "severity": "error"
  }
]

Exit Codes Reference

markdownlint-cli returns specific exit codes to help you handle execution outcomes in automated scripts:

Exit Code 0 — Success

Linting completed successfully, and no styling violations with a severity level of error were found. (Note: Warnings may still be printed, but they do not trigger a non-zero exit code).

Exit Code 1 — Lint Errors Identified

One or more rules flagged active errors in your documents. Fix these errors manually or run with the --fix parameter to resolve them.

Exit Code 2 — Output Write Failure

The CLI was unable to save reports to the file path specified with -o or --output (e.g. due to directory permission restrictions or a missing target directory path).

Exit Code 3 — Custom Rules Load Failure

One or more custom rule paths specified with -r or --rules could not be loaded. Ensure the file extensions are valid, and verify NPM packages are installed correctly.

Exit Code 4 — Unexpected Configuration or Parsing Error

An unhandled system or configuration exception occurred (e.g., trying to parse a malformed configuration file, or resolving an invalid --configPointer path).