yq - YAML Command-Line Processor

yq is a lightweight, portable command-line YAML processor. Written in Go with no dependencies, it uses jq-like syntax but works with YAML, JSON, XML, INI, CSV, and TSV files.

Installation

brew install yq

Basic Syntax

Read Values

yq '.name' pokemon.yaml                    # Get name field
yq '.stats.hp' pokemon.yaml                # Nested field access
yq '.[0].name' pokemon.yaml                # First element's name

Process from Stdin

cat pokemon.yaml | yq '.name'
echo 'name: Pikachu' | yq '.name'

Field Access

Dot Notation

yq '.pokemon[0].name' file.yaml            # First Pokemon's name
yq '.pokemon[0].stats.speed' file.yaml     # Nested stats

Array Access

yq '.pokemon[0]' file.yaml                 # First element
yq '.pokemon[-1]' file.yaml                # Last element
yq '.pokemon[0:3]' file.yaml               # First 3 elements

Iterate All Items

yq '.pokemon[].name' file.yaml             # All names
yq '.pokemon[] | .name' file.yaml          # Same with pipe

Modifying Values

Update Fields

yq '.name = "Raichu"' pokemon.yaml
yq '.stats.hp = 60' pokemon.yaml

In-Place Updates

yq -i '.legendary = true' pokemon.yaml
yq -i '.stats.speed = 120' pokemon.yaml

Add New Fields

yq '.region = "Kanto"' pokemon.yaml
yq '.moves = ["Thunder", "Quick Attack"]' pokemon.yaml

Delete Fields

yq 'del(.temporary_field)' pokemon.yaml
yq 'del(.stats.unused)' pokemon.yaml

Filtering with select()

# Find legendary Pokemon
yq '.pokemon[] | select(.legendary == true)' pokemon.yaml

# Find by type
yq '.pokemon[] | select(.type[] == "Fire")' pokemon.yaml

# Find by stat threshold
yq '.pokemon[] | select(.stats.speed > 100)' pokemon.yaml

# Multiple conditions
yq '.pokemon[] | select(.region == "Kanto" and .legendary == true)' pokemon.yaml

Array Operations

Collect Results

yq '[.pokemon[].name]' file.yaml           # All names as array
yq '[.pokemon[] | select(.legendary)]' file.yaml

Array Length

yq '.pokemon | length' file.yaml

Append to Array

yq '.type += ["Electric"]' pokemon.yaml

Format Conversion

YAML to JSON

yq -o=json pokemon.yaml
yq -o=json '.' pokemon.yaml > pokemon.json

JSON to YAML

yq -P pokemon.json                         # Pretty YAML output
yq -Poy pokemon.json                       # Explicit YAML output

Common Flags

Flag	Description
-i	Edit file in-place
-o=json	Output as JSON
-o=yaml	Output as YAML
-P	Pretty print
-n	Null input (create from scratch)
-e	Exit with error if no matches
--front-matter	Process YAML front matter in markdown

Working with Multiple Files

Merge Files

yq -n 'load("base.yaml") * load("override.yaml")'

Evaluate All

yq ea '. as $item ireduce ({}; . * $item)' file1.yaml file2.yaml

Environment Variables

yq '.api_key = strenv(API_KEY)' config.yaml
NAME="Pikachu" yq '.name = strenv(NAME)' pokemon.yaml

Practical Examples

Extract All Pokemon Names

yq '.pokemon[].name' pokedex.yaml

Find Fast Fire Types

yq '[.pokemon[] | select(.type[] == "Fire" and .stats.speed > 80)]' pokedex.yaml

Update All Pokemon Regions

yq -i '.pokemon[].region = "Kanto"' pokedex.yaml

Convert Pokedex to JSON

yq -o=json '.' pokedex.yaml > pokedex.json

Tips

1. Use -i carefully - it modifies files in place
2. Test expressions without -i first
3. Use yq -P for readable output
4. Wrap complex expressions in single quotes
5. Use select() for filtering, not array indexing

Related

• Jq - JSON processor (similar syntax)
• Yq Frontmatter Manipulation - Working with markdown frontmatter

Resources

• Official Docs: https://mikefarah.gitbook.io/yq/
• GitHub: https://github.com/mikefarah/yq