yq
a lightweight and portable command-line YAML processor
The aim of the project is to be the jq or sed of yaml files.
New version!
V3 is officially out - if you've been using v2 and want/need to upgrade, checkout the upgrade guide.
Install
Download the latest binary
MacOS:
brew install yq
Windows:
choco install yq
Supported by @chillum
snap
packages:
Ubuntu and other Linux distros supporting snap install yq
Snap notes
yq
installs with with strict confinement in snap, this means it doesn't have direct access to root files. To read root files you can:
sudo cat /etc/myfile | yq r - a.path
And to write to a root file you can either use sponge:
sudo cat /etc/myfile | yq w - a.path value | sudo sponge /etc/myfile
or write to a temporary file:
sudo cat /etc/myfile | yq w - a.path value | sudo tee /etc/myfile.tmp
sudo mv /etc/myfile.tmp /etc/myfile
rm /etc/myfile.tmp
On Ubuntu 16.04 or higher from Debian package:
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys CC86BB64
sudo add-apt-repository ppa:rmescandon/yq
sudo apt update
sudo apt install yq -y
Supported by @rmescandon
Go Get:
GO111MODULE=on go get github.com/mikefarah/yq/v3
Run with Docker
Oneshot use:
docker run --rm -v "${PWD}":/workdir mikefarah/yq yq [flags] <command> FILE...
Run commands interactively:
docker run --rm -it -v "${PWD}":/workdir mikefarah/yq sh
It can be useful to have a bash function to avoid typing the whole docker command:
yq() {
docker run --rm -i -v "${PWD}":/workdir mikefarah/yq yq "$@"
}
Features
- Written in portable go, so you can download a lovely dependency free binary
- Colorize the output
- Deep read a yaml file with a given path expression
- List matching paths of a given path expression
- Return the lengths of arrays/object/scalars
- Update a yaml file given a path expression or script file
- Update creates any missing entries in the path on the fly
- Deeply compare yaml files
- Keeps yaml formatting and comments when updating
- Validate a yaml file
- Create a yaml file given a deep path and value or a script file
- Prefix a path to a yaml file
- Convert to/from json to yaml
- Pipe data in by using '-'
- Merge multiple yaml files with various options for overriding and appending
- Supports multiple documents in a single yaml file for reading, writing and merging
Usage
Check out the documentation for more detailed and advanced usage.
Usage:
yq [flags]
yq [command]
Available Commands:
compare yq x [--prettyPrint/-P] dataA.yaml dataB.yaml 'b.e(name==fr*).value'
delete yq d [--inplace/-i] [--doc/-d index] sample.yaml 'b.e(name==fred)'
help Help about any command
merge yq m [--inplace/-i] [--doc/-d index] [--overwrite/-x] [--append/-a] sample.yaml sample2.yaml
new yq n [--script/-s script_file] a.b.c newValue
prefix yq p [--inplace/-i] [--doc/-d index] sample.yaml a.b.c
read yq r [--printMode/-p pv] sample.yaml 'b.e(name==fr*).value'
validate yq v sample.yaml
write yq w [--inplace/-i] [--script/-s script_file] [--doc/-d index] sample.yaml 'b.e(name==fr*).value' newValue
Flags:
-C, --colors print using colors
-h, --help help for yq
-I, --indent int sets indent level for output (default 2)
-P, --prettyPrint pretty print
-j, --tojson output as json. By default it prints a json document in one line, use the prettyPrint flag to print a formatted doc.
-v, --verbose verbose mode
-V, --version Print version information and quit
Use "yq [command] --help" for more information about a command.