yq
a lightweight and portable command-line YAML processor
The aim of the project is to be the jq or sed of yaml files.
Install
MacOS:
Using Homebrew
brew install yq
Ubuntu and other Linux distros supporting snap
packages:
snap install yq
Snap notes
yq
installs 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
wget
Use wget to download the pre-compiled binaries:
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY} -O /usr/bin/yq &&\
chmod +x /usr/bin/yq
For instance, VERSION=3.4.1 and BINARY=yq_linux_amd64
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 "$@"
}
Go Get:
GO111MODULE=on go get github.com/mikefarah/yq/v3
As these are supported by the community ❤ - however, they may be out of date with the officially supported releases.
Windows:
choco install yq
Supported by @chillum (https://chocolatey.org/packages/yq)
Mac:
Using MacPorts
sudo port selfupdate
sudo port install yq
Supported by @herbygillot (https://ports.macports.org/maintainer/github/herbygillot)
Alpine Linux
- Enable edge/community repo by adding
$MIRROR/alpine/edge/community
to /etc/apk/repositories
- Update database index with
apk update
- Install yq with
apk add yq
Supported by Tuan Hoang
https://pkgs.alpinelinux.org/package/edge/community/x86/yq
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 (https://launchpad.net/~rmescandon/+archive/ubuntu/yq)
Features
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'
shell-completion Generates shell completion scripts
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 with 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.
Upgrade from V2
If you've been using v2 and want/need to upgrade, checkout the upgrade guide.
V4 is in development!
If you're keen - check out the alpha release here, or in docker mikefarah/yq:4-beta1
and the docs (also in beta) here.
V4 is quite different from V3 (sorry for the migration), however it will be much more similar to jq
, use a similar expression syntax and therefore support much more complex functionality!
For now - new features will be held off from V3 in anticipation of the V4 build. Critical fixes / issues will still be released.
Known Issues / Missing Features