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 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:
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 failedcheck --fixwrite, 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, noYAMLLINT_CONFIG_FILE, no discovered.ryl.toml/.yamllint) and no--enable. Create a config that enables rules, runryl 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:
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:
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:
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.
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:
.ryl.tomlryl.toml.config/.ryl.toml.config/ryl.tomlpyproject.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:
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.
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:
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 > ryl.toml<br/>> .config/.ryl.toml > .config/ryl.toml<br/>> 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 > 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.