Yq

Common Use Cases:

• Parse Kubernetes manifests
• Modify Docker Compose files
• Update CI/CD configurations (.gitlab-ci.yml, .github/workflows)
• Extract values from config files
• Merge YAML files
• Convert between YAML and JSON

Installation Check

# Check version
yq --version
# Should output: yq (https://github.com/mikefarah/yq/) version v4.x.x

# NOT the Python yq wrapper which shows: yq 3.x.x

Basic Syntax

General Form

yq [options] 'expression' [file...]

Common Options:

• -i / --inplace - Edit file in place
• -o FORMAT / --output-format FORMAT - Output format (yaml/json/xml/props)
• -P / --prettyPrint - Pretty print (default for YAML)
• -I INDENT / --indent INDENT - Set indent (default: 2)
• -r / --raw-output - Output raw strings (no quotes)
• -n / --null-input - Don't read input
• -e / --exit-status - Exit with status based on output

Input/Output

# From file
yq '.name' config.yaml

# From stdin
echo 'name: Alice' | yq '.name'

# From command output
kubectl get pod mypod -o yaml | yq '.spec.containers[0].image'

# Multiple files
yq '.version' app1.yaml app2.yaml

Essential Operations

1. Read Values

# Simple field
echo 'name: Alice' | yq '.name'
# Output: Alice

# Nested field
echo 'user: {name: Alice, age: 30}' | yq '.user.name'
# Output: Alice

# Array element
echo 'items: [a, b, c]' | yq '.items[0]'
# Output: a

# All array elements
echo 'items: [a, b, c]' | yq '.items[]'
# Output: a b c (three separate outputs)

2. Raw Output (No Quotes)

# With quotes (default YAML)
echo 'name: Alice' | yq '.name'
# Output: Alice

# Raw output (like jq -r)
echo 'name: Alice' | yq -r '.name'
# Output: Alice

# Useful for shell variables
VERSION=$(yq -r '.version' package.yaml)

3. Modify Values

# Update field
echo 'name: Alice' | yq '.name = "Bob"'
# Output: name: Bob

# Update nested field
echo 'user: {name: Alice}' | yq '.user.age = 30'
# Output: 
# user:
#   name: Alice
#   age: 30

# In-place file edit
yq -i '.version = "2.0.0"' config.yaml

4. Add/Delete Fields

# Add new field
echo 'name: Alice' | yq '.age = 30'
# Output:
# name: Alice
# age: 30

# Delete field
echo 'name: Alice