Kubernetes manifests, Compose files, and every half-finished config in your repo speak YAML. yq makes them queryable instead of sacred.
This page covers mikefarah/yq (Go) — the one you get from brew install yq — not the Python wrapper with the same name. It speaks a jq-like expression language over YAML, and can round-trip JSON, YAML, and more. Read a value, rewrite a key, convert formats, or fail a script when a field is missing. If jq is how you survive APIs, yq is how you survive deployment config without opening a GUI.
install
# macOS (mikefarah/yq)
brew install yq
yq --version
# Debian/Ubuntu — pin mikefarah binary if distro yq is the Python one
sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq
# Fedora
sudo dnf install yq
# Arch
sudo pacman -S yq
examples
# Read a nested value
yq '.a.b' config.yaml
# YAML → JSON (pipe into jq if you want)
yq -o=json '.' config.yaml
# JSON → YAML
printf '{"name":"gray","ok":true}\n' | yq -p=json -o=yaml
# In-place set (always commit first; -i rewrites the file)
yq -i '.image.tag = "1.4.2"' values.yaml
# Delete a key
yq -i 'del(.metadata.annotations)' manifest.yaml
# Merge two files (second wins on conflicts)
yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yaml overlay.yaml
# Fail scripts when missing (exit non-zero)
yq -e '.required_field' config.yaml >/dev/null
pro tip
Run yq --version once on every new machine. If you silently got the Python kislyuk/yq, half these flags will not exist and you will waste an hour. mikefarah prints a version like v4.x.x.
honest limits
YAML is a landmine language (Norway problem, yes/no booleans, anchor merge keys). yq helps you edit it; it does not make every document sane. Huge multi-doc Helm output can be slow — filter earlier. In-place -i rewrites formatting; use a git diff before you trust it on sacred files. And for pure JSON APIs, stay on jq — yq is the YAML bridge, not a jq replacement.