Yq
External
Internal
Overview
Obsolete
yq is a lightweight and portable command-line YAML processor. It is written in Go and it consists in a single portable binary. It can be used to query a YAML file using a YAML path, to update a YAML file for a YAML path or using a script file, to create a YAML file or merge YAML files. The update operation creates any missing path elements. yq can also be used to convert YAML files to JSON and JSON files to YAML.
The default output is YAML, unless -j option is used.
Version
yq --version yq version 2.4.1
Installation
Mac
brew install yq
Upgrade
brew upgrade yq
Install a Specific Version
Linux
Go to https://github.com/mikefarah/yq/releases to figure out what the latest release is.
yq_version=3.4.1
cd /tmp
wget https://github.com/mikefarah/yq/releases/download/${yq_version}/yq_linux_amd64
mv /tmp/yq_linux_amd64 /bin/yq
chmod a+x /bin/yq
For 4.x, the version has a preceding "v":
yq_version=v4.33.3
cd /tmp
wget https://github.com/mikefarah/yq/releases/download/${yq_version}/yq_linux_amd64
mv /tmp/yq_linux_amd64 /bin/yq
chmod a+x /bin/yq
Maintain Co-existing yq 3 and yq 4 Versions
wget -O /usr/local/bin/yq3 https://github.com/mikefarah/yq/releases/download/3.4.1/yq_darwin_amd64
chmod +x /usr/local/bin/yq3
In scripts:
shopt -s expand_aliases
alias yq=yq3
Concepts
Command Line Options
-v
Provides additional details on parsing.
-j
Output formatted as JSON.
Operations
Conversion to and from JSON
Also see
YAML to JSON
yq r <file> -j
JSON to YAML
yq r <file.json>
Read
yq r <file.yaml> <path> cat <file.yaml> | yq r - <path>
If the path does not exist - either the final element, or intermediary elements - , yq returns literally "null", but the return code is 0.
If the path exists, but the content is empty, yq returns "null".
Checking yq-validity
An empty file or a file that only contains commands is invalid for for yq. This can be checked as follows:
if ! yq r file.yaml 1>/dev/null 2>/dev/null; then echo "file.yaml invalid" fi
Expressions
Arrays
Select elements from an array.
All elements:
...<enclosing-element-name>[*]
First element:
...<enclosing-element-name>[0]
Specific keys from all elements:
...<enclosing-element-name>[*].<some-key>
Maps
Organizatorium
If an array contains single key maps, selecting one of them with:
yq -r ./file.yaml spec.template.spec.volumes[*].configMap
Create a New YAML Document
yq n <path> <value>
The content is sent to stdout.
Example:
yq n test.color blue > test.yaml
Result:
test:
color: blue
Write/Update a YAML Document
The command takes the file specified as a base and writes/updates the specified paths. It then sends the entire resulted YAML file at stdout.
If the base is empty, or only contains comments, yq w fails with:
Error: asked to process document index 0 but there are only 0 document(s)
"yq-validity" can be checked with yq r command.
Starting from test.yaml:
item:
color: blue
yq w test.yaml item.color red
produces:
item:
color: red
The command can add a new path, creating all required path elements:
yq w test.yaml item.size large
produces:
item:
color: blue
size: large
The command may update the file in-place by specifying the "-i" option:
yq w -i test.yaml ...
write Idiosyncrasies:
- write strips off the comments from the base file
Merge YAML Documents
YAML files can be merged using the 'merge' (m) command. Each additional file merged with the first file will set values for any key not existing already or where the key has no value.
Delete Paths
yq d ./some-file.yaml a.b.c
Deletes the subtree identified by the right-most path element, including the element. The deletion happens even if the subtree is empty.
If the document does not contain an element identified by the right-most path element, the operation is a noop.