yq Cheatsheet

Power user.

Overview

yq is the YAML processor that does for YAML what jq does for JSON. Mikefarah’s implementation uses jq-compatible syntax, which means fluency transfers directly. Five primitive surfaces cover almost every YAML manipulation operators need: read fields, modify in place, convert between YAML and JSON, handle multi-document streams, and chain transforms together.

• YAML reading. Path expressions select fields out of arbitrarily nested structures. Cleaner than grep plus cut.
• YAML modification. Update or add fields with -i for in-place edits. Reviewable diffs replace ad-hoc sed.
• YAML to JSON conversion. -o=json bridges YAML configs into JSON-only tooling pipelines.
• Multi-document streams plus jq-compatible syntax. Kubernetes manifests with --- separators handled natively; jq fluency transfers without retraining.

The approach

Five expressions cover almost every operational use of yq. Memorising them turns YAML editing from a bug-prone shell exercise into reviewable transformations.

• yq '.spec.replicas' file.yaml. Read a field. The starting point for every investigation of a config value.
• yq '.spec.replicas = 3' -i file.yaml. Update in place. Declarative edits the next reviewer can read in a diff.
• yq -o=json file.yaml. Convert to JSON. Bridges YAML configs into tools that only consume JSON.
• yq 'select(.kind == "Deployment")' k8s.yaml plus pipelines. Filter multi-document streams; chain transforms with |= for composable edits.

Why this compounds

Each yq one-liner replaces a manual edit or a fragile sed pattern. Config-management speed grows; CI scripts become readable. Modern infrastructure is YAML-first, which means fluency pays back across Kubernetes, GitHub Actions, GitLab CI, Helm values, and most cloud-config formats.

• Faster config edits. One-liners replace manual editing or brittle sed patterns.
• Composable pipelines. Structured input and output mean yq chains cleanly with jq and kubectl.
• Universal applicability. Kubernetes, CI configs, Helm values, cloud-config. YAML is everywhere; yq works everywhere.
• Year-one investment, year-two habit. First year builds fluency. By year two, yq is the default for any structured edit.