Release v1.14.0 · the useful surface, audited

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
source-aware edits

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◆ FLOW + BLOCK SURGERY◆ TRIM + SPLIT DOC◆ 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.

Every YAML-oriented yq area is marked supported, focused, or excluded—with a named test behind the claim.

Open the operator manifest

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

Change the node. Keep the file.

Edits compile into owned source spans after evaluation. Flow collections, block scalars, records, comments, and reorders stay surgical; --preserve-only refuses the rest.

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.14.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.