YAML in shell. No, really.

YAML.sh queries, transforms, validates, and edits YAML in one readable POSIX shell file with portable AWK inside. Common edits keep the comments and formatting around them.

ysh '.books[] | select(.read) | .title' reading.yml
ysh --preserve-only --diff '.theme = "midnight"' settings.yml
ysh --schema settings.schema.json '.' settings.yml

Pick a task#

• Install one file and run your first query.
• Copy a working recipe for common tasks.
• Learn the query language.
• Validate against a schema, apply a patch, or convert formats.
• Edit one file or many — preview first, write safely.
• Choose the output format.

What it can do#

• Query and transform. Use paths, pipes, filters, reducers, construction, and updates across files and YAML documents.
• Edit carefully. Preview changes with --check or --diff; use --preserve-only when comments and formatting must stay put.
• Validate, patch, and convert. Apply JSON Schema, JSON Patch, and Merge Patch, or move between YAML, JSON, TOML, INI, and XML; expression codecs cover properties, CSV, and TSV.
• Inspect strange input. View types, source locations, parser events, an AST, or an explanation of an edit.

The released ysh contains the complete shell launcher and AWK engine. Copy one file, read it, and run it without another language runtime.

What's supported — and what isn't#

• YAML support records accepted and rejected syntax.
• Queries defines the expression language.
• Validate, patch, and convert defines schemas, patches, and non-YAML formats.
• Security and limits explains optional capabilities, resource ceilings, and write behavior.

Unsupported syntax fails clearly rather than returning a plausible result.

Open the hood#

ysh --events config.yml
ysh --ast config.yml
ysh --explain=json --diff '.image.tag = "stable"' services/*.yml 2>changes.jsonl

The internals guide follows a document through parsing, evaluation, output, and careful source edits. The development guide explains the codebase and test suite.