yq
YAML/JSON Cheatsheet
yq
command-line YAML processor
Is a lightweight and portable command-line YAML processor, using jq
like syntax that works with YAML
and
JSON
files.
JSON Schema enables the confident and reliable use of the JSON data format.
Installation
# Linux
$ VERSION=v4.43.1
$ BINARY=yq_linux_amd64
$ sudo wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY} -O /usr/bin/yq
$ sudo chmod +x /usr/bin/yq
$ brew install yq # MacOS
$ winget install --id MikeFarah.yq # Windows
$ winget upgrade yq -s winget # Upgrading on Windows
YAML Example
$ cat flintstones.yaml
---
family: Flintstones
members:
- Name: Fred
Age: 35
Gender: male
- Name: Wilma
Age: 25
Gender: female
- Name: Pebbles
Age: 1
Gender: female
- Name: Dino
Age: 5
Gender: male
Pretty print YAML (in color)
$ yq flintstones.yaml
---
family: flintstones
members:
- Name: Fred
Age: 35
Gender: male
- Name: Wilma
Age: 25
Gender: female
- Name: Pebbles
Age: 1
Gender: female
- Name: Dino
Age: 5
Gender: male
$ yq '.members' flintstones.yaml
[
{
"Name": "Fred",
"Age": 35,
"Gender": "male"
},
{
"Name": "Wilma",
"Age": 25,
"Gender": "female"
},
{
"Name": "Pebbles",
"Age": 1,
"Gender": "female"
},
{
"Name": "Dino",
"Age": 5,
"Gender": "male"
}
]
Evaluate YAML
Evaluate the given expression against each yaml document in each file, in sequence
Filtering
$ yq '.members[].Name' flintstones.yaml
Fred
Wilma
Pebbles
Dino
$ yq '.members[] | .Name' flintstones.yaml
Fred
Wilma
Pebbles
Dino
$ yq '.members[].Name,.members[].Age' flintstones.yaml
Fred
Wilma
Pebbles
Dino
35
25
1
5
# $ jq '.members[] | .Name,.Age' flintstones.json - does not work, equivalent
$ yq '.members[] | with_entries(select(.key | test("Name|Age")))' flintstones.yaml
Name: Fred
Age: 35
Name: Wilma
Age: 25
Name: Pebbles
Age: 1
Name: Dino
Age: 5
$ yq '.members[1].Name,.members[1].Age' flintstones.yaml
Wilma
25
Keys and lengths
$ yq '. | keys' flintstones.yaml
- family
- members
$ yq '.members[0] | keys' flintstones.yaml
- Name
- Age
- Gender
$ yq '. | length' flintstones.yaml # 2
$ yq '.members | length' flintstones.yaml # 4
$ yq '.members[] | length' flintstones.yaml # 3 3 3 3
$ yq '.members[].Name | length' flintstones.yaml # 4 5 7 4
JSON Example
$ cat flintstones.json
{
"family": "Flintstones",
"members": [
{ "Name": "Fred", "Age": 35, "Gender": "male" },
{ "Name": "Wilma", "Age": 25, "Gender": "female" },
{ "Name": "Pebbles", "Age": 1, "Gender": "female" },
{ "Name": "Dino", "Age": 5, "Gender": "male" }
]
}
Pretty print JSON (in color)
$ yq flintstones.json
{
"family": "flintstones",
"members": [
{
"Name": "Fred",
"Age": 35,
"Gender": "male"
},
{
"Name": "Wilma",
"Age": 25,
"Gender": "female"
},
{
"Name": "Pebbles",
"Age": 1,
"Gender": "female"
},
{
"Name": "Dino",
"Age": 5,
"Gender": "male"
}
]
}
$ yq '.members' flintstones.json
[
{
"Name": "Fred",
"Age": 35,
"Gender": "male"
},
{
"Name": "Wilma",
"Age": 25,
"Gender": "female"
},
{
"Name": "Pebbles",
"Age": 1,
"Gender": "female"
},
{
"Name": "Dino",
"Age": 5,
"Gender": "male"
}
]
Evaluate JSON
Evaluate the given expression against each yaml document in each file, in sequence
Filtering
$ yq '.members[].Name' flintstones.json
"Fred"
"Wilma"
"Pebbles"
"Dino"
$ yq '.members[] | .Name' flintstones.json
"Fred"
"Wilma"
"Pebbles"
"Dino"
# $ jq '.members[] | .Name,.Age' flintstones.json - does not work, equivalent
$ yq '.members[] | with_entries(select(.key | test("Name|Age")))' flintstones.json
{
"Name": "Fred",
"Age": 35
}
{
"Name": "Wilma",
"Age": 25
}
{
"Name": "Pebbles",
"Age": 1
}
{
"Name": "Dino",
"Age": 5
}
Keys and lengths
$ yq '. | keys' flintstones.json
[
"family",
"members"
]
$ yq '.members[0] | keys' flintstones.json
[
"Name",
"Age",
"Gender"
]
$ yq '. | length' flintstones.json # 2
$ yq '.members | length' flintstones.json # 4
$ yq '.members[] | length' flintstones.json # 3 3 3 3
$ yq '.members[].Name | length' flintstones.json # 4 5 7 4
Conversion
Various conversions and formatting options are possible see, Usage
$ yq -oy '.' flintstones.toml # convert TOML to YAML
$ yq -oy '.' flintstones.xml # convert XML to YAML
$ yq -oy '.' flintstones.json # convert JSON to YAML
$ yq -oj '.' flintstones.yaml # convert YAML to JSON
$ yq -oj '.' flintstones.xml # convert XML to JSON
$ yq -oj '.' flintstones.toml # convert TOML to JSON
$ yq -ox '.' flintstones.yaml # convert YAML to XML
$ yq -ox '.' flintstones.json # convert JSON to XML
$ yq -ox '.' flintstones.toml # convert TOML to XML