Release v1.11.0 · see the write before it happens

yq energy.
zero baggage.

Program YAML with one portable shell script. No package manager. No language runtime. No mystery binary. Just /bin/sh, AWK, and a frankly unreasonable amount of ambition.

Get YAML.sh Read the docs

1 file
0 runtime installs
exact edit previews

config.yml — ysh POSIX

1services:

2 - name: api

3 enabled: true

4 - name: worker

5 enabled: false

6 - name: web

7 enabled: true

$ ysh '.services[] | select(.enabled) | .name' config.yml

api
web

MAP + REDUCE◆ COMMENTS SURVIVE◆ PIPES + SELECT◆ ANCHORS + ALIASES◆ MERGE KEYS◆ TAGS + TYPES◆ EMPTY COLLECTIONS◆ DIFF BEFORE WRITE◆ STRICT PRESERVATION◆ CROSS-FILE UPDATES◆ TRANSACTIONAL EDITS

Structure all the way through

It parses before it queries.

YAML.sh parses a proper node graph before evaluating expressions. Mappings, sequences, tags, anchors, aliases, and source lines stay intact from input to output.

Read

Portable AWK recognizes mappings, sequences, flow nodes, scalars, tags, anchors, and documents.

Resolve

Aliases and merge sources connect through node identity, with precedence and recursion validation.

Program

Paths, reducers, assignments, graph metadata, and repository transactions operate on real node references with identity and type intact.

Tiny commands. Serious YAML.

Meet the CLI.

Compose files without inviting another runtime.

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

Collections become clean, typed JSON.

$ ysh -o=json '.services[0]' config.yml
{"name":"api","enabled":true,"port":8080}

See the candidate. 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 # promoted by CI
+  tag: stable # promoted by CI

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

Built for the machines between machines.

Bootstrap containers, CI runners, old Macs, tiny servers, and recovery shells. If the system has /bin/sh and AWK, YAML.sh is ready.

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 / TESTED

Know what works.

Supported syntax, rejected edge cases, resource limits, and yq overlap are tested and documented in plain language.

Explore 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 / OBSERVABLE

Repository edits explain themselves.

--diff shows the exact prepared write. --preserve-only refuses noisy regeneration. Commits skip no-ops, roll back failures, and can record value-free paths.

Field note · August 2026

The YAML parser that got out of hand.

An old Bash experiment became a measured, yq-shaped language in one increasingly unreasonable day. This is the story of the constraint, the evidence, 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.11.0

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

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

yq energy.zero baggage.