YAML Linter CLI and API

Common errors

• Error: YAMLLINT_SCHEMA environment variable value is not a valid schema type.

  cause An unsupported or misspelled schema name was provided via the `YAMLLINT_SCHEMA` environment variable.
  fix Set `YAMLLINT_SCHEMA` to one of the valid schema types: `DEFAULT_SCHEMA`, `FAILSAFE_SCHEMA`, `JSON_SCHEMA`, or `CORE_SCHEMA`.

• Cannot find module 'yaml-lint'

  cause The `yaml-lint` package is not installed or not accessible in the current project's `node_modules`.
  fix Run `npm install --save-dev yaml-lint` for local project usage or `npm install -g yaml-lint` for global CLI use.

• SyntaxError: Unexpected token 'export'

  cause Attempting to use `require()` on a module that primarily uses ES Modules syntax in an environment that doesn't correctly transpile or resolve ESM.
  fix Ensure your Node.js environment supports ESM (Node.js 12+ with 'type: module' in package.json, or file extension .mjs). Alternatively, use `import yamlLint from 'yaml-lint';` in an ESM context.

Warnings

• breaking Node.js 0.x is no longer supported. Users on older Node.js versions must upgrade to at least Node.js 8 or newer.
  Fix: Upgrade your Node.js runtime to version 8 or higher. The current package targets modern Node.js environments.
• gotcha When configuring ignore patterns, always use forward slashes (e.g., `dir/*.yaml`) regardless of the operating system. Backslashes on Windows might lead to patterns not being correctly applied.
  Fix: Ensure all `ignore` glob patterns consistently use forward slashes. This was specifically fixed in v1.7.0 to enforce forward slashes, but user input still needs to adhere to this.
• deprecated The `nocase` rule for glob patterns was removed in an earlier version (1.2.3) to prevent issues on Windows. This might affect how case-insensitive file matching works for ignore patterns.
  Fix: Adjust glob patterns to be explicit about case if necessary, as automatic case-insensitivity might not be applied as expected across all platforms.
• gotcha By default, the CLI will only display the first failing file it encounters. To see all failing files, ensure you are using a version that supports displaying multiple errors.
  Fix: Update to `yaml-lint` version 1.4.0 or newer to ensure all failing files are reported when using the CLI.

Install

• npm install yaml-lint npm
• yarn add yaml-lint yarn
• pnpm add yaml-lint pnpm

Imports

• yamlLint
  wrong:

  const yamlLint = require('yaml-lint');

  correct:

  import yamlLint from 'yaml-lint';

  While CommonJS `require` still works for the main export, `yaml-lint` migrated to TypeScript and ES2015+ syntax in v1.3.0 and v1.1.0 respectively. For modern Node.js and bundled environments, ESM imports are preferred.
• lint

  import yamlLint from 'yaml-lint';
  yamlLint.lint('...');

  The primary programmatic function is accessed as a method on the default export. There is no direct named export for `lint` itself.
• Types

  import type { LintOptions } from 'yaml-lint';

  Since v1.3.0, the package ships with TypeScript types. Specific types for options or results can be imported directly.

Quickstart

Demonstrates both direct string linting and how to lint the content of a file using the programmatic API.

import yamlLint from 'yaml-lint';
import { readFileSync } from 'fs';
import { join } from 'path';

// Example 1: Linting a string directly
yamlLint
  .lint('key: value\narray:\n  - item1\n  - item2')
  .then(() => {
    console.log('String content is valid YAML.');
  })
  .catch((error) => {
    console.error('String content is invalid YAML:', error.message);
  });

// Example 2: Linting a file (assuming a test.yaml exists for this example)
const filePath = join(process.cwd(), 'test.yaml');
// To make this runnable, create a dummy test.yaml for demonstration:
// fs.writeFileSync(filePath, 'foo: bar\nversion: 1.0');

// For a real scenario, ensure 'test.yaml' exists and contains valid YAML
try {
  const fileContent = readFileSync(filePath, 'utf8');
  yamlLint.lint(fileContent)
    .then(() => console.log(`${filePath} is valid YAML.`))
    .catch(error => console.error(`${filePath} is invalid YAML:`, error.message));
} catch (err) {
  console.warn(`Could not read ${filePath}. Please create it for file linting demo.`);
  // Example of how you'd explicitly fail a file lint for a broken file:
  // yamlLint.lint('invalid: - \n  - yaml')
  //   .catch(error => console.error('Intentional invalid file content error:', error.message));
}