ryl 0.5.0

Fast YAML linter inspired by yamllint

ryl

ryl - the Rust Yaml Linter is intended to ultimately be a drop in replacement for yamllint. It is usable today, but parity and edge-case behavior are still maturing.

Compatibility note:

• ryl aims to match yamllint behavior and includes many parity tests.
• ryl uses the saphyr parser stack, while yamllint uses the PyYAML parser stack.
• saphyr and PyYAML do not always agree on which files are valid YAML.

Quick Start

# Using uv (Python)
uvx ryl .

# Using npx (Node.js)
npx @owenlamont/ryl .

For prek / pre-commit integration, see ryl-pre-commit.

Installation

uv

uv tool install ryl

NPM

npm install -g @owenlamont/ryl

pip

pip install ryl

Cargo

cargo install ryl

Usage

ryl accepts one or more paths: files and/or directories.

Basic:

ryl <PATH_OR_FILE> [PATH_OR_FILE...]

Behavior:

• Files: parsed as YAML even if the extension is not .yml/.yaml.
• Directories: recursively lints .yml and .yaml files.
  • Respects .gitignore, global git ignores, and git excludes.
  • Does not follow symlinks.

Exit codes:

• 0 when all parsed files are valid (or no files found).
• 1 when any invalid YAML is found.
• 2 for CLI usage errors (for example, no paths provided).

Examples:

# Single file
ryl myfile.yml

# Multiple inputs (mix files and directories)
ryl config/ another.yml

# Multiple directories
ryl dir1 dir2

# Explicit non-YAML extension (parsed as YAML)
ryl notes.txt

Help and version:

Fast YAML linter written in Rust

Usage: ryl [OPTIONS] [PATH_OR_FILE]...

Arguments:
  [PATH_OR_FILE]...  One or more paths: files and/or directories

Options:
  -c, --config-file <FILE>           Path to configuration file (YAML or TOML)
  -d, --config-data <YAML>           Inline configuration data (yaml)
  -f, --format <FORMAT>              Output format (auto, standard, colored, github,
                                     parsable) [default: auto]
                                     [possible values: auto, standard, colored,
                                     github, parsable]
      --fix                          Apply safe fixes in place before reporting
                                     remaining diagnostics
      --migrate-configs              Convert discovered legacy YAML config files
                                     into .ryl.toml files
      --list-files                   List files that would be linted (reserved)
  -s, --strict                       Strict mode (reserved)
      --no-warnings                  Suppress warnings (reserved)
      --migrate-root <DIR>           Root path to search for legacy YAML config
                                     files (default: .)
      --migrate-write                Write migrated .ryl.toml files (otherwise
                                     preview only)
      --migrate-stdout               Print generated TOML to stdout during migration
      --migrate-rename-old <SUFFIX>  Rename source YAML configs by appending
                                     this suffix after migration
      --migrate-delete-old           Delete source YAML configs after migration
  -h, --help                         Print help
  -V, --version                      Print version

Performance benchmarking

This repo includes a standalone benchmark script that compares PyPI ryl and yamllint using synthetic YAML corpora and hyperfine.

Prerequisites:

• uv
• hyperfine

Run a quick sample:

uv run scripts/benchmark_perf_vs_yamllint.py --file-counts 25,100 --file-sizes-kib 1,8 --runs 5 --warmup 1

Run a fuller matrix (explicit lists):

uv run scripts/benchmark_perf_vs_yamllint.py --file-counts 25,100,400,1000 --file-sizes-kib 1,8,32,128 --runs 10 --warmup 2

Run a fuller matrix (ranges with increments):

uv run scripts/benchmark_perf_vs_yamllint.py --file-count-start 100 --file-count-end 1000 --file-count-step 100 --file-size-start-kib 4 --file-size-end-kib 64 --file-size-step-kib 4 --runs 10 --warmup 2

The script uses Typer; use --help for all options.

Artifacts are written under manual_outputs/benchmarks/<UTC_TIMESTAMP>/:

• benchmark.png and benchmark.svg: side-by-side facet plot with shared Y axis.
• summary.csv: aggregated timing table.
• meta.json: tool versions and run parameters.
• hyperfine-json/: raw results from hyperfine.

Example benchmark figure (5x5 matrix, 5 runs per point):

Configuration

• Flags:
  • -c, --config-file <FILE>: path to a YAML or TOML config file.
  • -d, --config-data <YAML>: inline YAML config (highest precedence).
  • --fix: apply safe fixes in place before reporting remaining diagnostics.
  • --list-files: print files that would be linted after applying ignores and exit.
  • --migrate-configs: discover legacy YAML configs and plan TOML migration.
  • --migrate-root <DIR>: root to search for legacy YAML configs (default .).
  • --migrate-write: write migrated .ryl.toml files (without this it is preview-only).
  • --migrate-stdout: print generated TOML in migration mode.
  • --migrate-rename-old <SUFFIX>: rename discovered legacy YAML config files after writing.
  • --migrate-delete-old: delete discovered legacy YAML config files after writing.
  • -f, --format, -s, --strict, --no-warnings: reserved for compatibility.
• Discovery precedence: inline --config-data > --config-file > env YAMLLINT_CONFIG_FILE (global) > nearest project config up the tree: TOML (.ryl.toml, ryl.toml, pyproject.toml with [tool.ryl]) then YAML fallback (.yamllint, .yamllint.yml, .yamllint.yaml)

  user-global ($XDG_CONFIG_HOME/yamllint/config or ~/.config/yamllint/config) > built-in defaults.

• Rules Documentation: see docs/rules.md for a full list of supported rules and their fixable status.
• TOML and YAML are not merged during discovery. If a TOML project config is found, YAML project config discovery is skipped (and ryl prints a warning).
• Native fix policy is TOML-only. YAML config remains yamllint-compatible and does not support fix settings.
• Per-file behavior: unless a global config is set via --config-data, --config-file, or YAMLLINT_CONFIG_FILE, each file discovers its nearest project config. Ignores apply to directory scans and explicit files (parity).
• Presets and extends: supports yamllint’s built-in default, relaxed, and empty via extends. Rule maps are deep-merged; scalars/sequences overwrite.
• TOML preset examples: see docs/config-presets.md for default/relaxed equivalents.

Example TOML config (.ryl.toml):

yaml-files = ["*.yaml", "*.yml"]
ignore = ["vendor/**", "generated/**"]
locale = "en_US.UTF-8"

[rules]
document-start = "disable"

[rules.line-length]
max = 120

[rules.truthy]
allowed-values = ["true", "false"]

[fix]
fixable = ["ALL"]
unfixable = []

Migration example:

# Preview migration actions
ryl --migrate-configs --migrate-root .

# Write .ryl.toml files and keep old files with a suffix
ryl --migrate-configs --migrate-root . --migrate-write --migrate-rename-old .bak

Acknowledgements

This project exists thanks to the tooling and ecosystems around YAML linting and developer automation, especially:

• yamllint - for giving me the shoulders to stand on and the source of many of the automated tests that ryl uses now to check for behaviour parity. Copying the behaviour of an existing tool is infinitely easier than building one from scratch - there'd be no ryl without yamllint.
• ruff - for showing the power of Rust tooling for Python development and inspiring the config and API for ryl.
• rumdl - for giving me another template to follow for Rust tooling and showing me almost the only dev tool I was still using after this that wasn't written in Rust was yamllint (which inspired me to tackle this project)
• saphyr - ryl is built on saphyr and saphyr's developers were very patient in showing some of the nuance and complexity of parsing YAML which I was embarrassingly ignorant of when start ryl.
• esbuild and biome - for providing the "binary wrapper" blueprint for distributing high-performance native tools via NPM.