yq/README.md

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

Download the latest binary

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.0 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

Community Supported Installation methods

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

• 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
• General shell completion scripts (bash/zsh/fish/powershell) (https://mikefarah.gitbook.io/yq/commands/shell-completion)

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'
  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 the docs (also in alpha) 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

• yq attempts to preserve comment positions and whitespace as much as possible, but it does not handle all scenarios (see https://github.com/go-yaml/yaml/tree/v3 for details)
• You cannot (yet) select multiple paths/keys from the yaml to be printed out (https://github.com/mikefarah/yq/issues/287) (although you can in v4!)