Release v1.17.0 · one readable executable

YAML in shell.
No, really.

Query, transform, validate, and edit YAML with one portable sh + awk file. It has no business working this well.

Get YAML.sh Read the docs

1 file
sh + awk runtime
keeps comments

reading.yml — ysh POSIX

1books:

2 - title: Piranesi

3 read: true

4 - title: Dune

5 read: false

6 - title: Kindred

7 read: true

$ ysh '.books[] | select(.read) | .title' reading.yml

Piranesi
Kindred

QUERY + TRANSFORM◆ COMMENTS SURVIVE◆ ANCHORS + ALIASES◆ DIFF BEFORE WRITE◆ ONE READABLE FILE

Built for the whole job

Find it. Change it. Keep the comments.

Run expressions over YAML structure, preview the result, and write it back without needlessly reformatting the file.

Query

Select, filter, map, reduce, and combine values across files and YAML documents.

Change

Build, update, delete, validate, patch, and convert while YAML types and relationships stay intact.

Review

Check or diff first. Write only when ready, and require preservation when formatting must stay put.

Small command. Deep YAML.

Meet the CLI.

Combine two YAML files with one expression.

$ ysh ea 'select(fileIndex == 0) * select(fileIndex == 1)' defaults.yml production.yml
{"replicas":3,"region":"west"}

Validate a file, apply a standard patch, and preview the result.

$ ysh --schema deploy.schema.json --apply-patch promote.json --diff deploy.yml
--- a/deploy.yml
+++ b/deploy.yml
@@ -4 +4 @@
-  tag: old
+  tag: stable

Preview exactly what will change. Keep the comments. Then write.

$ ysh --preserve-only --diff '.image.tag = "stable"' services/api.yml
--- a/services/api.yml
+++ b/services/api.yml
@@ -3,1 +3,1 @@
-  tag: old # keep this comment
+  tag: stable # keep this comment

Open the hood whenever the YAML gets weird.

$ ysh --type '.release.date' config.yml
timestamp

$ ysh --ast config.yml
node  1  mapping  line=1

01 / PORTABLE

Portable on purpose.

Query with /bin/sh and AWK. Check and write with ordinary host file utilities. No extra language runtime required.

macOS AWKmawk + original AWKBusyBox + POSIX gawk

02 / PRECISE

Keys stay keys.

Use .["key.with.dots"] when punctuation belongs to the YAML—not the query.

03 / DOCUMENTED

Know what works.

See the supported YAML syntax, query language, schema profile, patches, formats, and security limits.

See YAML support

04 / HACKABLE

One file. Open book.

The shipped executable contains the complete shell launcher and AWK engine. Read it, copy it, bend it.

05 / CAREFUL

Edit YAML. Keep the comments.

Common scalar, collection, block, comment, and reorder edits leave unrelated text alone. --preserve-only refuses the rest.

Field note · August 2026

The YAML parser that got out of hand.

An old Bash experiment grew into one improbably capable shell file in one increasingly unreasonable day. This is how the constraint shaped the tool, and what building it with Codex made possible.

Read the story

Install the current release

One pipe.
Then go query something.

The installer downloads and checksum-verifies a pinned release, then places ysh in /usr/local/bin. Set YSH_INSTALL_DIR to choose another location.

Terminalv1.17.0

curl -fsSL https://yaml.azohra.com/install | sh

Homebrew: brew install azohra/tools/ysh
Prefer to inspect first? Read the installer source.

YAML in shell.No, really.