Skip to content

Quick start

The ryl check subcommand

ryl's CLI is moving to subcommands: ryl check is the lint pass and ryl format is the formatter. ryl check <paths> is the recommended form and is used throughout these docs. Bare ryl <paths> still lints identically, but it is deprecated — it prints a warning to stderr (silenced by --no-warnings) and a later release will remove it, so adopt ryl check now.

Run a lint

Create a config, then lint a file or directory:

ryl init
ryl check .

ryl init writes the default preset to .ryl.toml; use ryl init --preset relaxed for fewer checks. Ecosystem presets are ansible, cloudformation (including SAM), home-assistant, kubernetes (including Kustomize), github-actions, compose, helm, and gitlab-ci, for example ryl init --preset github-actions. Existing project configs in the current directory are refused. See Configuration presets.

Once configured, point ryl at a file or directory:

# Lint a single file
ryl check path/to/file.yaml

# Lint a project (recursively scans .yml/.yaml, honouring .gitignore)
ryl check .

ryl does not enable any rules by default, so these commands report no configuration found (exit 2) until a configuration or --enable turns on a rule. To start straight away, name the rules to run with --enable, which needs no config file:

ryl check --enable ALL .
ryl check --enable key-duplicates,truthy .
ryl check --enable ALL --disable line-length,truthy,document-start --exclude pnpm-lock.yaml .

or pass a TOML config inline with -d:

ryl check -d 'lint.rules = { key-duplicates = "enable", truthy = "enable" }' .

For a persistent ruleset, use ryl init (see Configure for your project below).

Rule and file selection flags

Flag Effect
--enable <RULES> Replace the config's lint selection; comma-separated IDs or ALL; repeatable
--disable <RULES> Subtract lint rules after config and --enable; comma-separated IDs or ALL; once per command
--exclude <GLOBS> Replace config exclusions, including exclude-from-file; comma-separated gitignore-style globs relative to the current directory; once per command

Unknown rule IDs exit 2, with a closest-match suggestion for likely typos in flags or configuration. check also exits 2 when the final selection enables no lint rules. --disable alone never enables rules. Both flags work with check --fix and check --diff, and with the deprecated bare invocation. --exclude also applies to --list-files and format, including explicitly named files; use --exclude '' to clear config exclusions. With stdin, exclusions apply only when --stdin-filename supplies a path. See File ignores.

format --disable suppresses the named lint rules' conflict warnings; formatter passes remain controlled by [format], independently of lint rule selection.

Caching

ryl check and ryl format cache file results by content, resolved configuration, YAMLLINT_FILE_ENCODING, and ryl version. The default .ryl_cache/<version>/ is in the current directory, including when -c selects a config elsewhere. The cache directory contains .gitignore and CACHEDIR.TAG; deleting it clears all results.

Use --no-cache or RYL_NO_CACHE=1 to bypass both result and remote schema caches. Remote schemas use a separate user cache. --cache-dir PATH, RYL_CACHE_DIR, and the TOML-only top-level cache-dir = "PATH" select another location, in that precedence order. A relative path in TOML is resolved from the project root; a relative CLI or environment path uses the current directory. Cache directory failures, including symlinked cache directories, exit 2; corrupt entries are recomputed. Stdin, diff output, and editor requests do not use the disk cache. Format results for encoded files or filenames unsuitable for diff headers are not cached, so format --check keeps their skip notices.

Lint from stdin

Pass - as the input to read YAML from standard input — useful for editor integrations where the buffer is not yet on disk:

cat file.yaml | ryl check -

# Provide a filename so diagnostics, config discovery, and
# yaml-files / per-file-ignores match the right path:
cat file.yaml | ryl check - --stdin-filename path/to/file.yaml

Without --stdin-filename, diagnostics are labelled <stdin>, config discovery is anchored at the current working directory, and all path-based filtering (yaml-files, per-file-ignores, per-rule ignore patterns) is skipped so every enabled rule runs. - cannot be combined with other inputs, and --fix cannot read from stdin (use --diff to preview fixes instead).

Exit codes:

  • 0 — no problems found.
  • 1 — lint errors, invalid YAML, or a path that could not be read (including nonexistent files).
  • 2 — CLI usage error (no inputs provided, bad flags), a failed check --fix write, or strict mode was enabled and only warnings were produced.

--strict (-s) enables strict mode; --no-strict disables strict mode even when configured in TOML. See Strict mode for project configuration.

Config migration exits 2 for a wholly skipped source or a refused write. Approximations and retained source directives exit 0 with warnings, or 2 under --strict; a clean rerun exits 0.

ryl never enables a rule unless a configuration or --enable explicitly turns it on, so two cases exit 2 rather than silently linting nothing:

  • No configuration found anywhere (no -c/-d, no YAMLLINT_CONFIG_FILE, no discovered .ryl.toml/.yamllint) and no --enable. Create a config that enables rules, run ryl init, or pass --enable ALL.
  • A configuration that enables no rules (rules: {}, an empty [lint.rules]/[tool.ryl], or one disabling everything), or a selection emptied by --disable. Enable at least one rule in the existing configuration, or pass --enable ALL.

Apply auto-fixes

ryl can automatically fix a subset of rules:

ryl check --fix .

See the Rules reference for which rules are fixable.

If a write fails, --fix names the file on stderr, continues with other files, and exits 2 even when other files have lint findings. Failed files do not count as fixed in the summary. Where commas and brackets (or braces) disagree on the gap before a closing bracket, as yamllint's defaults do on [a,], --fix drops the trailing comma.

--fix rewrites files in place but never writes through a symlink: a symlinked input is linted but skipped for fixing (with a warning on stderr), so a symlink in an untrusted tree cannot redirect a write to a file outside it. This mirrors directory scanning, which does not follow symlinks.

Format

ryl format rewrites files to a consistent layout, and needs no config:

ryl format .
ryl format --check .

See Formatter for what it changes and how to configure it.

Preview fixes as a diff

--diff runs the same safe fixes as --fix but, instead of writing, prints a unified diff (3 lines of context) of what would change to stdout — modelled on ruff check --diff:

ryl check --diff .

This is handy for CI previews, PR review, and parallel-safe runners such as hk that apply the diff themselves rather than re-invoking the linter. --diff never modifies files, is mutually exclusive with --fix, and (unlike --fix) works with -/stdin.

Diff headers use paths relative to the current directory for files beneath it. On Windows, headers use forward slashes and omit the \\?\ verbatim prefix, so the patch applies with git apply -p0. ryl format --diff uses the same headers. Filenames retain trailing dots and spaces, including on Windows. Windows drive-relative inputs such as C:input.yaml resolve from that drive's current directory.

Like ruff check --diff, the exit code reflects only the diff — remaining unfixable findings are neither printed nor counted:

  • 1 — at least one file would change.
  • 0 — no file would change.
  • 2 — usage/config error or an input-processing failure.

A file that cannot be parsed (or a symlink) is skipped with a notice on stderr and does not affect the exit code. Non-UTF-8 and BOM-prefixed files emit no patch, but still exit 1 when a fix would change the decoded text; use --fix (see File encodings). For embedded YAML in Markdown, the diff is reported at the host-file level (one diff per .md).

File encodings

ryl auto-detects UTF-8 (with or without a BOM), UTF-16 LE/BE, and UTF-32 LE/BE: the encodings required by YAML 1.2. A BOM identifies the encoding; without a BOM, null-byte patterns identify UTF-16/32, otherwise ryl uses UTF-8.

Other encodings, such as Latin-1, fail with a decode error unless named via YAMLLINT_FILE_ENCODING (for example, latin-1). Prefer converting to UTF-8; the yamllint-compatible override prints:

YAMLLINT_FILE_ENCODING is meant for temporary workarounds. It may be removed in a future version of yamllint.

ryl check --fix and ryl format preserve the original encoding and BOM; ryl format - preserves stdin's encoding in stdout.

For BOM/UTF-16/UTF-32 input, --diff reports that no applicable text patch can be emitted. ryl check --diff still exits 1 when a fix would change the decoded text, including stdin and embedded YAML in Markdown. ryl format --check and ryl format --diff likewise exit 1 when formatting would change the text.

LSP position encoding counts columns, independently of file encoding.

Configure for your project

The recommended TOML config is deliberately explicit and local: it has no default-on rules and no extends/inheritance, so a single .ryl.toml (discovered by searching upward, and preferred over a .yamllint) is the entire ruleset for the files beneath it; a monorepo can have many, each governing its subtree. When no project config is found, ryl falls back to a single user-global config (see below). Either way there are no default-on rules, so a config that enables nothing exits 2 without --enable rather than silently linting nothing.

Drop a .ryl.toml (or ryl.toml) at the root of your repo. Settings shared by every pass ([files], exclude/exclude-from-file, [markdown], locale, [output], line-length, indent-width, target-version) sit at the top level; linter settings sit under [lint] (strict, [lint.rules], fixable/unfixable, [lint.per-file-ignores], [[lint.per-line-ignores]]); [format] holds the formatter's settings. Run ryl init (or choose --preset for your ecosystem) and customise the generated preset:

[files]
yaml = [
    "*.yaml",
    "*.yml",
    ".yamllint",
]

# ... rule enable/disable table from the preset ...

[lint.rules.line-length]
max = 120
allow-non-breakable-words = true

The top-level line-length (1 to 65535) and indent-width (1 to 255) are the formatter's targets and the defaults for [lint.rules.line-length] max and [lint.rules.indentation] spaces; an explicit rule option overrides them for linting only. Unset, max is 80, spaces is "consistent", and ryl format uses width 2. Set indent-width to preserve another width. A YAML config cannot set these top-level keys.

For selected expression-like scalars, TOML-only [[format.prose]] entries configure files, path, break-before tokens and optional protected-patterns regexes. Entries apply only with [format] prose-wrap = "always"; the first file/path match wins.

line-length = 100
indent-width = 4

The top-level target-version ("1.1", the default, or "1.2") names the oldest YAML version whose readers must load ryl format and --fix output to the same values. See YAML version compatibility.

YAML configuration (.yamllint) is deprecated: ryl still discovers it, and its extends: can still merge in a preset, but each use warns. Convert it to .ryl.toml as described in Migrating from yamllint.

To keep config out of the project root, ryl also discovers a ryl-native TOML config inside a repo-local .config/ directory (the RuboCop/rumdl convention). At each directory in the upward search the candidates are tried in this order, and the first match wins:

  1. .ryl.toml
  2. ryl.toml
  3. .config/.ryl.toml
  4. .config/ryl.toml
  5. pyproject.toml (only when it has a [tool.ryl] table)

.config/ holds ryl-native TOML only: the legacy .yamllint/.yamllint.yaml/ .yamllint.yml files are discovered at the directory level, never inside .config/. A .config/ryl.toml is a true drop-in for a root ryl.toml: its [files]/exclude globs and relative exclude-from-file paths resolve against the project root (the directory containing .config/), not .config/ itself.

If you already have a yamllint configuration, use the built-in converter:

ryl --migrate-configs --migrate-write

The converter also imports a formatter config found beside yamllint. Follow After migrating to verify diagnostics, clean up old configs and update CI.

Earlier releases put [rules], [fix], per-file-ignores and per-line-ignores at the top level. ryl still reads them, but warns once per key, naming its [lint] replacement; when both spellings are set, the [lint] one wins. The same ryl --migrate-configs --migrate-write rewrites such a .ryl.toml/ryl.toml in place, keeping comments and key order (add --migrate-rename-old .bak to keep the original as .ryl.toml.bak), and ryl --migrate-user-config --migrate-write does the same for the user-global config. For pyproject.toml the command only prints the keys to move.

Strict mode

Set strict = true under [lint] to return exit code 2 for warning-only lint results, including check --fix and stdin. The default is false.

[lint]
strict = true

In pyproject.toml, use [tool.ryl.lint] instead. Strict mode is TOML-only. Precedence is CLI (--strict/--no-strict) > config > default; the two CLI flags are mutually exclusive. Like [output], strict mode uses the first configuration discovered from the run's inputs when spanning projects; pass -c or -d to choose one explicitly. --no-warnings still suppresses warnings, and --diff keeps its existing exit codes. ryl format is unaffected.

Lint alongside ryl format

If you run ryl format, let it own layout and lint only what it never touches. This starter config enables the rules that catch YAML that loads to something other than what the author meant, and conflicts with no [format] setting:

[lint.rules]
anchors = "enable"
key-duplicates = "enable"
truthy = "enable"

[lint.per-file-ignores]
".github/workflows/*" = ["truthy"]

Gate CI on both:

ryl format --check .
ryl check .

The truthy ignore keeps GitHub Actions' on: key from being reported (see truthy). Add any other rule from the Rules reference as you need it; the Formatter page lists the layout rules and the options that conflict with ryl format. If you do not run ryl format, start from a preset instead, which keeps the layout rules.

Configure across projects (user-global)

When no project config is found, ryl falls back to a user-global config so you can set personal defaults once. It reads its own TOML config first — <config-dir>/ryl/.ryl.toml (or ryl.toml), following the ruff/Biome convention where <config-dir> is $XDG_CONFIG_HOME if set, else the platform-native config dir (~/.config/ryl on Linux, ~/Library/Application Support/ryl on macOS, %APPDATA%\ryl on Windows) — then falls back to yamllint's <config-dir>/yamllint/config, which is deprecated and warns. A project config, -c/-d, or YAMLLINT_CONFIG_FILE all take precedence over the user-global config. YAMLLINT_CONFIG_FILE is deprecated and accepts only a yamllint YAML config (pointing it at a .toml errors); use -c for ryl-native TOML.

If you have a yamllint user-global config, ryl --migrate-user-config --migrate-write converts it to the ryl-native ryl.toml (see Migrating from yamllint).

Configuration precedence

ryl resolves the configuration governing each file it lints, trying these sources in order and stopping at the first hit. -d/-c and YAMLLINT_CONFIG_FILE pin a single config for the whole run; otherwise project discovery runs per file, so a monorepo can hold many .ryl.toml files, each governing its own subtree. The winning config must enable at least one rule, or --enable must name one, or ryl exits 2:

flowchart TD
    Start([resolve config]) --> D{"-d / --config-data?"}
    D -->|yes| UseInline["use inline TOML,<br/>or YAML (deprecated)"] --> Done([config resolved])
    D -->|no| C{"-c / --config-file?"}
    C -->|yes| UseFile["load file: TOML, or YAML<br/>(deprecated) by extension"] --> Done
    C -->|no| P{"project config?<br/>walk up from inputs to HOME"}
    P -->|"TOML up-tree"| UseProjToml["nearest TOML:<br/>.ryl.toml &gt; ryl.toml<br/>&gt; .config/.ryl.toml &gt; .config/ryl.toml<br/>&gt; pyproject.toml [tool.ryl]"] --> Done
    P -->|"else .yamllint up-tree"| UseProjYaml["nearest .yamllint /<br/>.yamllint.yaml / .yamllint.yml<br/>(deprecated)"] --> Done
    P -->|none| E{"YAMLLINT_CONFIG_FILE set?"}
    E -->|"points at .toml"| Err1["error: use -c / project discovery<br/>for ryl TOML (exit 2)"]
    E -->|"YAML and exists"| UseEnv["load as yamllint YAML<br/>(deprecated)"] --> Done
    E -->|"missing or unset"| G{"user-global config?"}
    G -->|"ryl TOML"| UseRyl["config-dir/ryl/.ryl.toml &gt; ryl.toml"] --> Done
    G -->|"else yamllint YAML"| UseYl["config-dir/yamllint/config<br/>(deprecated)"] --> Done
    G -->|none| N{"--enable?"}
    N -->|yes| UseEmpty["empty config"] --> Done
    N -->|no| Err2["error: no configuration found (exit 2)"]
    Done --> R{"any rule enabled,<br/>after --enable / --disable?"}
    R -->|yes| OK([lint])
    R -->|no| Err3["error: no rules enabled (exit 2)"]
    classDef default stroke-width:3px;
    linkStyle default stroke-width:3px;

JSON Schemas

The TOML-only schema rule adds JSON Schema validation. Configure [[lint.rules.schema.schemas]] with a relative path or HTTPS url and optional files globs. The first matching association wins; empty files matches all inputs. Local schemas and references must remain under the config base directory. Remote resources require independent origin grants; see the schema controls for flags, environment variables and the user allowlist. A config without schema associations performs no schema work.