yq-yaml-processing

yq YAML Processing

Expert knowledge for processing, querying, and transforming YAML data using yq v4+, the lightweight command-line YAML processor with jq-like syntax.

When to Use This Skill

Use this skill when...	Use another skill instead when...
Querying or modifying YAML files	The input is JSON only — use jq-json-processing
Editing YAML in place while preserving comments and key order	Multi-step transforms spanning YAML, JSON, CSV, TOML — use nushell-data-processing
Targeted updates to a Kubernetes manifest or Actions workflow	Full Kubernetes management (use kubectl); XML (use xmlstarlet)
Merging YAML configurations	Aggregating or grouping across many files — use nushell-data-processing

Core Expertise

YAML Operations

• Query and filter YAML with path expressions
• Transform YAML structure and shape
• Multi-document YAML support
• Convert between YAML, JSON, XML, and other formats

Configuration Management

• Modify Kubernetes manifests
• Update GitHub Actions workflows
• Process Helm values files
• Manage application configurations

Essential Commands

Basic Querying

# Pretty-print YAML
yq '.' file.yaml

# Extract specific field
yq '.fieldName' file.yaml

# Extract nested field
yq '.spec.containers[0].name' pod.yaml

# Access array element
yq '.[0]' array.yaml
yq '.items[2]' data.yaml

Reading YAML

# Read specific field
yq '.metadata.name' deployment.yaml

# Read nested structure
yq '.spec.template.spec.containers[].image' deployment.yaml

# Read with default value
yq '.optional // "default"' file.yaml

# Check if field exists
yq 'has("fieldName")' file.yaml

Modifying YAML (In-Place)

# Update field value
yq -i '.metadata.name = "new-name"' file.yaml

# Update nested field
yq -i '.spec.replicas = 3' deployment.yaml

# Add new field
yq -i '.metadata.labels.app = "myapp"' file.yaml

# Delete field
yq -i 'del(.spec.nodeSelector)' file.yaml

# Append to array
yq -i '.items += {"name": "new-item"}' file.yaml

# Update all matching elements
yq -i '(.items[] | select(.name == "foo")).status = "active"' file.yaml

Multi-Document YAML

# Split multi-document YAML
yq -s '.metadata.name' multi-doc.yaml

# Select specific document (0-indexed)
yq 'select(document_index == 0)' multi-doc.yaml

# Process all documents
yq eval-all '.' multi-doc.yaml

# Filter documents
yq 'select(.kind == "Deployment")' k8s-resources.yaml

# Combine YAML files
yq eval-all '. as $item ireduce ({}; . * $item)' file1.yaml file2.yaml

Object Operations

# Get all keys
yq 'keys' file.yaml

# Select specific fields
yq '{name, version}' file.yaml

# Merge objects
yq '. * {"updated": true}' file.yaml
yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yaml override.yaml

# Deep merge
yq eval-all '. as $item ireduce ({}; . *+ $item)' base.yaml override.yaml

JSON Output (for piping)

# YAML to JSON
yq -o=json '.' file.yaml

# Compact single-line JSON — the form to pipe into jq or a tool that reads stdin
yq -o=json -I=0 '.' file.yaml

Quick Reference

Operators

• .field - Access field
• .[] - Iterate array/object
• | - Pipe (chain operations)
• , - Multiple outputs
• // - Alternative operator (default value)
• * - Merge objects (shallow)
• *+ - Deep merge objects

Functions

• keys, values - Object keys/values
• length - Array/object/string length
• select() - Filter
• sort_by() - Sort
• group_by() - Group
• unique - Remove duplicates
• has() - Check field existence
• type - Get value type
• add - Sum or concatenate
• del() - Delete field

Flags

Flag	Description
-i	In-place edit
-o	Output format (json, yaml, xml, csv, tsv, props)
-p	Input format (json, yaml, xml)
-I	Indent (default: 2)
-r	Raw output (no quotes)
-n	Null input (create from scratch)
-s	Split multi-document YAML

String Functions

• split(), join() - String/array conversion
• contains() - String/array contains
• test() - Regex match
• sub(), gsub() - String substitution
• upcase, downcase - Case conversion

For detailed examples, advanced patterns, and best practices, see REFERENCE.md.

Resources

• Official Documentation: https://mikefarah.gitbook.io/yq/
• GitHub Repository: https://github.com/mikefarah/yq
• Try with Docker: docker run --rm -i mikefarah/yq '.key' <<< 'key: value'
• Operators Reference: https://mikefarah.gitbook.io/yq/operators/