ryl

https://ryl-docs.pages.dev/
Admin
ryl is a fast YAML linter written in Rust designed for speed, drop-in yamllint compatibility, and...
Tokens:58,355
Snippets:596
Trust Score:7.2
Update:1 week ago
Show doc for...
Tokens:
Raw
### Allowed example (defaults)

Source: https://ryl-docs.pages.dev/rules/brackets

Example of a flow sequence with no spaces inside brackets, which is allowed by default.

```yaml
object: [1, 2, abc]
```

--------------------------------

### Install ryl with winget

Source: https://ryl-docs.pages.dev/getting-started/installation

Install ryl using winget on Windows.

```bash
winget install owenlamont.ryl

```

--------------------------------

### Allowed example (defaults)

Source: https://ryl-docs.pages.dev/rules/commas

Example of a flow sequence and mapping with correct comma spacing: `list: [10, 20, 30, {x: 1, y: 2}]`.

```yaml
list: [10, 20, 30, {x: 1, y: 2}]

```

--------------------------------

### Allowed example with present: true

Source: https://ryl-docs.pages.dev/rules/document-start

Example of a YAML document that starts with the `---` marker, which is allowed when `present: true`.

```yaml
---
title: example

```

--------------------------------

### Install ryl with npm

Source: https://ryl-docs.pages.dev/getting-started/installation

Install ryl globally using npm.

```bash
npm install --global @owenlamont/ryl

```

--------------------------------

### Install ryl with pixi or conda

Source: https://ryl-docs.pages.dev/getting-started/installation

Install ryl using pixi global install or conda from conda-forge.

```bash
pixi global install ryl
# or: conda install -c conda-forge ryl

```

--------------------------------

### Install fish completions

Source: https://ryl-docs.pages.dev/getting-started/shell-completions

Writes the completion script to ~/.config/fish/completions/ryl.fish. fish loads it automatically on the next shell.

```bash
mkdir -p ~/.config/fish/completions
ryl --generate-completions fish > ~/.config/fish/completions/ryl.fish

```

--------------------------------

### Reported example (defaults)

Source: https://ryl-docs.pages.dev/rules/brackets

Example of a flow sequence with spaces inside brackets, which is reported by default because `min-spaces-inside` and `max-spaces-inside` are 0.

```yaml
object: [ 1, 2, abc ]
```

--------------------------------

### Install elvish completions

Source: https://ryl-docs.pages.dev/getting-started/shell-completions

Adds this line to ~/.config/elvish/rc.elv to load completions.

```elvish
eval (ryl --generate-completions elvish | slurp)

```

--------------------------------

### Install ryl and lint a file or directory

Source: https://ryl-docs.pages.dev/

Install ryl using Cargo, pip, npm, conda-forge, or winget, then run `ryl check` on a file or directory. The command `ryl check .` lints the current directory.

```bash
# Install with Cargo
cargo install ryl

# Or with pip
pip install ryl

# Or with npm
npm install --global @owenlamont/ryl

# Or with conda (conda-forge)
pixi global install ryl

# Or with winget (Windows)
winget install owenlamont.ryl

# Lint a file or directory
ryl check path/to/file.yaml
ryl check .
```

--------------------------------

### Allowed example (defaults)

Source: https://ryl-docs.pages.dev/rules/empty-lines

YAML document with up to two consecutive empty lines, which is allowed under default settings.

```yaml
---
a: 1

b: 2


c: 3

```

--------------------------------

### Reported example (defaults)

Source: https://ryl-docs.pages.dev/rules/commas

Example of a flow sequence and mapping with incorrect comma spacing: `list: [10, 20 ,30,   {x: 1,   y: 2}]`.

```yaml
list: [10, 20 ,30,   {x: 1,   y: 2}]

```

--------------------------------

### Verify ryl installation

Source: https://ryl-docs.pages.dev/getting-started/installation

Check that ryl is installed correctly by printing its version.

```bash
ryl --version

```

--------------------------------

### Install bash completions system-wide

Source: https://ryl-docs.pages.dev/getting-started/shell-completions

Writes the bash completion script to /etc/bash_completion.d/ryl. Requires the bash-completion package.

```bash
ryl --generate-completions bash | sudo tee /etc/bash_completion.d/ryl > /dev/null

```

--------------------------------

### Install ryl with pip

Source: https://ryl-docs.pages.dev/getting-started/installation

Install ryl using pip, the Python package manager.

```bash
pip install ryl

```

--------------------------------

### Install zsh completions

Source: https://ryl-docs.pages.dev/getting-started/shell-completions

Writes the completion script as _ryl into ~/.zfunc. A new shell is needed to load it.

```bash
mkdir -p ~/.zfunc
ryl --generate-completions zsh > ~/.zfunc/_ryl

```

--------------------------------

### Install ryl Agent Skill with gh skill install

Source: https://ryl-docs.pages.dev/using-ryl-with-ai-agents

Installs the ryl Agent Skill for Claude Code. Replace --agent with cursor, codex, antigravity, github-copilot, or others; run gh skill install --help for the full list.

```bash
gh skill install owenlamont/ryl ryl --agent claude-code --scope user

```

--------------------------------

### Configuration for quoted-strings rule

Source: https://ryl-docs.pages.dev/rules/quoted-strings

Example configuration for the quoted-strings rule with all options set to their defaults.

```toml
[rules.quoted-strings]
level = "warning"
quote-type = "any"
required = true
extra-required = []
extra-allowed = []
allow-quoted-quotes = false
allow-double-quotes-for-escaping = false  # ryl-only
check-keys = false

```

--------------------------------

### Install ryl with Cargo

Source: https://ryl-docs.pages.dev/getting-started/installation

Install ryl using Cargo, the Rust package manager.

```bash
cargo install ryl

```

--------------------------------

### Start ryl LSP server

Source: https://ryl-docs.pages.dev/editor-integration

Starts the ryl language server, which communicates over stdin/stdout. The server is not run directly; instead, point your editor's LSP client at this command. Note that 'server' is a subcommand, so to lint a path literally named 'server' use 'ryl check server'.

```bash
$ ryl server

```

--------------------------------

### Reported example with present: true

Source: https://ryl-docs.pages.dev/rules/document-start

Example of a YAML document without the `---` marker, which is reported when `present: true`.

```yaml
title: example

```

--------------------------------

### Install PowerShell completions

Source: https://ryl-docs.pages.dev/getting-started/shell-completions

Adds this line to your PowerShell profile ($PROFILE) so completions load on each session.

```powershell
ryl --generate-completions powershell | Out-String | Invoke-Expression

```

--------------------------------

### Examples of per-line-ignores entries

Source: https://ryl-docs.pages.dev/per-line-ignores

Two example entries: one suppresses all rules on lines matching a machine-generated marker, and another suppresses the `braces` rule on lines with Go-template braces only in files matching `*.tpl.yaml`. Uses single-quoted TOML strings for patterns.

```toml
# Let machine-generated marker lines break any rule
[[per-line-ignores]]
regex = 'GENERATED — do not edit'
rules = ["ALL"]

# Allow Go-template braces, but only in template files
[[per-line-ignores]]
path = "*.tpl.yaml"
regex = '\{\{.*\}\}'
rules = ["braces"]

```

--------------------------------

### Allowed (defaults)

Source: https://ryl-docs.pages.dev/rules/colons

Example of allowed YAML with default spacing: one space after the colon and no spaces before.

```yaml
key: value
object:
  - a
  - b

```

--------------------------------

### Reported (defaults)

Source: https://ryl-docs.pages.dev/rules/colons

Example of reported YAML with default settings: a space before the colon and too many spaces after.

```yaml
key : value
key:   value

```

--------------------------------

### Allowed YAML values with defaults

Source: https://ryl-docs.pages.dev/rules/truthy

Example YAML with allowed truthy values: `enabled: true` and `visible: false`.

```yaml
enabled: true
visible: false

```

--------------------------------

### Reported example (defaults)

Source: https://ryl-docs.pages.dev/rules/empty-lines

YAML document with three consecutive empty lines, which violates the default `max = 2` and is reported.

```yaml
---
a: 1



b: 2

```

--------------------------------

### Allowed example: keys in alphabetical order

Source: https://ryl-docs.pages.dev/rules/key-ordering

A YAML mapping with keys in alphabetical order, which is allowed by the rule.

```yaml
---
alpha: 1
beta: 2
gamma: 3

```

--------------------------------

### Configuration for colons rule

Source: https://ryl-docs.pages.dev/rules/colons

Configuration example for the colons rule, setting level to error, max-spaces-before to 0, and max-spaces-after to 1.

```toml
[rules.colons]
level = "error"
max-spaces-before = 0
max-spaces-after = 1

```

--------------------------------

### Allowed example with ignored-keys: ["^x-"]

Source: https://ryl-docs.pages.dev/rules/key-ordering

A YAML mapping where a key matching the ignored-keys pattern can appear in any order, so this is allowed.

```yaml
---
x-trailing-extension: value
alpha: 1
beta: 2

```

--------------------------------

### Reported flow mapping (defaults)

Source: https://ryl-docs.pages.dev/rules/braces

Example of a flow mapping with spaces inside braces, which is reported when `min-spaces-inside` and `max-spaces-inside` are both `0`.

```yaml
object: { key1: 4, key2: 8 }
```

--------------------------------

### Reported comments with defaults

Source: https://ryl-docs.pages.dev/rules/comments

Reported example with default settings: missing space after the hash and only one space before the inline comment.

```yaml
#missing space after the hash
key: value # only one space before inline comment

```

--------------------------------

### Install bash completions for current user

Source: https://ryl-docs.pages.dev/getting-started/shell-completions

Creates the user completion directory and writes the script there. bash-completion searches ${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions.

```bash
dir="${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions"
mkdir -p "$dir"
ryl --generate-completions bash > "$dir/ryl"

```

--------------------------------

### Preview converted TOML with ryl --migrate-configs

Source: https://ryl-docs.pages.dev/getting-started/migrating-from-yamllint

Run from the project root. The first command previews the converted TOML without writing any files; the second writes .ryl.toml.

```bash
# Preview the converted TOML (no files written)
ryl --migrate-configs

# Write .ryl.toml
ryl --migrate-configs --write
```

--------------------------------

### Lint with --enable ALL

Source: https://ryl-docs.pages.dev/getting-started/quickstart

Use `--enable ALL` to run all rules without needing a configuration file.

```bash
ryl check --enable ALL .
```

--------------------------------

### Multiple outputs: JUnit and GitLab files

Source: https://ryl-docs.pages.dev/output-formats

Shows how to produce both a JUnit XML file and a GitLab JSON file in one run, with no console output. Each `--format` is paired with its own `-o`.

```bash
# a JUnit file and a GitLab file together, with no console output
$ ryl check --format junit -o report.xml --format gitlab -o gl.json .

```

--------------------------------

### Merge key example with ryl error output

Source: https://ryl-docs.pages.dev/rules/merge-keys

Example YAML using a merge key and the corresponding ryl error output. The error is reported at line 4, column 3, with message `forbidden merge key "<<"` and rule name `merge-keys`.

```yaml
defaults: &defaults
  retries: 3
prod:
  <<: *defaults
  host: prod.example.com

```

```text
4:3  error  forbidden merge key "<<"  (merge-keys)

```

--------------------------------

### Configuration for indentation rule

Source: https://ryl-docs.pages.dev/rules/indentation

Example configuration for the indentation rule, setting level to error, spaces to consistent, indent-sequences to true, and check-multi-line-strings to false.

```toml
[rules.indentation]
level = "error"
spaces = "consistent"
indent-sequences = true
check-multi-line-strings = false

```

--------------------------------

### Configuration for document-start rule

Source: https://ryl-docs.pages.dev/rules/document-start

Configuration block for the `document-start` rule, setting `level = "error"` and `present = true`.

```toml
[rules.document-start]
level = "error"
present = true

```

--------------------------------

### Reported example: keys out of order

Source: https://ryl-docs.pages.dev/rules/key-ordering

A YAML mapping with keys not in alphabetical order, which is reported by the rule.

```yaml
---
gamma: 3
alpha: 1
beta: 2

```

--------------------------------

### TOML config with `per-file-ignores`

Source: https://ryl-docs.pages.dev/file-ignores

Disables `document-start` for `**/values.yaml` and `truthy` for `.github/workflows/*` while still linting those files.

```toml
[rules.document-start]
present = true

[rules.truthy]

[per-file-ignores]
"**/values.yaml" = ["document-start"]
".github/workflows/*" = ["truthy"]

```

--------------------------------

### Configure outputs in TOML

Source: https://ryl-docs.pages.dev/output-formats

Shows how to set output formats in a project's TOML config under `[output]`. An absent `path` uses the format's default stream, `path = "-"` is stdout, and any other value is a file.

```toml
# keep the normal console output, and also write a GitLab report file
[output.auto]

[output.gitlab]
path = "gl-code-quality-report.json"

```

--------------------------------

### Example `.ryl.toml` configuration

Source: https://ryl-docs.pages.dev/getting-started/quickstart

A flat TOML configuration file that sets file patterns and a rule option. It is meant to be copied from a preset and customized. The `[files]` section lists YAML file globs, and `[rules.line-length]` sets `max` and `allow-non-breakable-words`.

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

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

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

```

--------------------------------

### Custom orders configuration for .pre-commit-config.yaml

Source: https://ryl-docs.pages.dev/rules/key-ordering

TOML configuration defining a custom key order for hooks in .pre-commit-config.yaml, with keys alias, name, description, args, env.

```toml
[rules.key-ordering]
level = "error"

[[rules.key-ordering.orders]]
files = [".pre-commit-config.yaml"]
path = "$.repos[*].hooks[*]"
keys = ["alias", "name", "description", "args", "env"]

```

--------------------------------

### Reported YAML values with defaults

Source: https://ryl-docs.pages.dev/rules/truthy

Example YAML with truthy values that are reported by default: `yes`, `On`, `NO`, and `True`.

```yaml
enabled: yes
flag: On
country: NO
debug: True

```

--------------------------------

### Reported: canonical key collision

Source: https://ryl-docs.pages.dev/rules/key-duplicates

An example where '0xB' and '11' are both the integer 11, reported when check-canonical is true.

```yaml
# 0xB and 11 are both the integer 11
0xB: a
11: b

```

--------------------------------

### Reported: duplicated merge keys

Source: https://ryl-docs.pages.dev/rules/key-duplicates

An example with two '<<' merge keys in the same mapping, reported when forbid-duplicated-merge-keys is true.

```yaml
base: &base {host: localhost}
extra: &extra {port: 8080}
server:
  <<: *base
  <<: *extra

```

--------------------------------

### Allowed YAML with explicit null

Source: https://ryl-docs.pages.dev/rules/empty-values

Example of YAML that is allowed by the rule because the value is explicitly set to `null`.

```yaml
---
some-key: value
explicit-null: null

```

--------------------------------

### Allowed flow mapping (defaults)

Source: https://ryl-docs.pages.dev/rules/braces

Example of an allowed flow mapping with no spaces inside braces, matching the default `min-spaces-inside` and `max-spaces-inside` of `0`.

```yaml
object: {key1: 4, key2: 8}
```

--------------------------------

### Example of explicit chomping indicator

Source: https://ryl-docs.pages.dev/rules/block-scalar-chomping

Shows a literal block scalar with a strip indicator (-) as required by the rule.

```yaml
script: |-
  echo "hello"

```

--------------------------------

### Allowed comments with defaults

Source: https://ryl-docs.pages.dev/rules/comments

Allowed example with default settings: a standalone comment with a space after the hash and an inline comment with two spaces of padding.

```yaml
# a properly spaced comment
key: value  # inline comment with two spaces of padding

```

--------------------------------

### Reported example with require-numeral-before-decimal: true

Source: https://ryl-docs.pages.dev/rules/float-values

YAML snippet showing a reported literal when require-numeral-before-decimal is true: .5 is not allowed.

```yaml
factor: .5
```

--------------------------------

### Reported: merge key shadowing

Source: https://ryl-docs.pages.dev/rules/key-duplicates

An example where an explicit key shadows a merged value, reported when forbid-merge-key-shadowing is true.

```yaml
# the explicit `timeout` shadows the merged one
defaults: &d {timeout: 30}
prod:
  <<: *d
  timeout: 60

```

--------------------------------

### Reported: merge-vs-merge collision

Source: https://ryl-docs.pages.dev/rules/key-duplicates

An example where two merged mappings define the same key 'x', reported when check-canonical is true.

```yaml
# both merged mappings define `x`; the second is silently dropped
a: &a {x: 1}
b: &b {x: 2}
c:
  <<: [*a, *b]

```
Tokens:
Raw