Features

• 24 configurable linting rules covering formatting, style, and correctness
• Multiple output formats: standard, parsable, colored, GitHub Actions
• Inline comment directives to suppress rules per-line or per-block
• Built-in default and relaxed configuration presets
• Recursive directory scanning with glob-based file filtering
• Strict mode with configurable severity levels (error/warning)
• Full CLI and programmatic API

Installation

npm install -g @asymmetric-effort/yamllint

Or as a dev dependency:

npm install --save-dev @asymmetric-effort/yamllint

Usage

CLI

# Lint a file
yamllint myfile.yaml

# Lint a directory recursively
yamllint ./config/

# Read from stdin
cat myfile.yaml | yamllint -

# Use a custom config
yamllint -c .yamllint.yaml myfile.yaml

# Inline config
yamllint -d "extends: relaxed" myfile.yaml

# Parsable output for CI
yamllint -f parsable .

# Strict mode (exit 2 on warnings)
yamllint --strict .

# List targeted files
yamllint --list-files .

Programmatic API

import { lint, loadConfig } from "@asymmetric-effort/yamllint";

const source = `---
key: value
`;

const { resolved } = loadConfig(undefined, "extends: default");
const result = lint(source, resolved);

for (const problem of result.problems) {
  console.log(`${problem.line}:${problem.column} [${problem.level}] ${problem.message}`);
}

Configuration

yamllint looks for configuration in these locations (in order):

1. .yamllint, .yamllint.yaml, or .yamllint.yml in the current or parent directories
2. File specified by $YAMLLINT_CONFIG_FILE environment variable
3. $XDG_CONFIG_HOME/yamllint/config (defaults to ~/.config/yamllint/config)
4. Built-in default configuration

Example Configuration

extends: default

rules:
  line-length:
    max: 120
    level: warning
  document-start: disable
  truthy:
    allowed-values: ["true", "false"]

Presets

| Preset | Description | |--------|-------------| | default | Strict — most rules enabled as errors | | relaxed | Lenient — disables comments/truthy, downgrades others to warnings |

Rules

| Rule | Type | Default | Description | |------|------|---------|-------------| | anchors | token | error | Validates anchor/alias usage | | braces | token | error | Controls spacing inside {} | | brackets | token | error | Controls spacing inside [] | | colons | token | error | Enforces colon spacing | | commas | line | error | Regulates comma spacing | | comments | comment | warning | Enforces comment formatting | | comments-indentation | comment | warning | Ensures comment alignment | | document-end | token | disabled | Manages ... marker | | document-start | token | warning | Requires/forbids --- marker | | empty-lines | line | error | Limits consecutive blank lines | | empty-values | token | disabled | Prevents implicit null values | | float-values | token | disabled | Controls float representations | | hyphens | token | error | Limits spaces after - | | indentation | line | error | Enforces consistent indentation | | key-duplicates | token | error | Prevents duplicate mapping keys | | key-ordering | token | disabled | Alphabetizes mapping keys | | line-length | line | error | Sets maximum line width | | new-line-at-end-of-file | line | error | Requires trailing newline | | new-lines | line | error | Standardizes line endings | | octal-values | token | disabled | Prevents octal value confusion | | quoted-strings | token | disabled | Controls string quoting | | trailing-spaces | line | error | Removes trailing whitespace | | truthy | token | warning | Restricts boolean representations |

Comment Directives

Suppress rules inline using comment directives:

# Disable a specific rule for one line
key: value  # yamllint disable-line rule:line-length

# Disable all rules for one line
key: value  # yamllint disable-line

# Disable rules for a block
# yamllint disable rule:colons
key : value
# yamllint enable rule:colons

# Disable all rules for the rest of the file
# yamllint disable-file

Output Formats

| Format | Description | |--------|-------------| | standard | Human-readable with filename header | | parsable | Machine-readable: file:line:col: [level] msg (rule) | | colored | Standard with ANSI colors | | github | GitHub Actions annotations | | auto | Detects environment (GitHub Actions, TTY color support) |

Exit Codes

| Code | Normal Mode | Strict Mode | |------|------------|-------------| | 0 | No errors | No errors or warnings | | 1 | Errors found | Errors found | | 2 | — | Warnings only |

Development

# Setup
make setup

# Run tests
make test

# Lint
make lint

# Build
make build

# Release
make release

License

MIT