.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "" "" ""
.hy
.SH yq
.PP
[IMAGE: Build (https://github.com/mikefarah/yq/workflows/Build/badge.svg)]
[IMAGE: Docker
Pulls (https://img.shields.io/docker/pulls/mikefarah/yq.svg)]
[IMAGE: Github Releases (by
Release) (https://img.shields.io/github/downloads/mikefarah/yq/total.svg)]
[IMAGE: Go
Report (https://goreportcard.com/badge/github.com/mikefarah/yq)]
.PP
a lightweight and portable command-line YAML processor.
\f[C]yq\f[R] uses jq (https://github.com/stedolan/jq) like syntax but
works with yaml files as well as json.
It doesn\[cq]t yet support everything \f[C]jq\f[R] does - but it does
support the most common operations and functions, and more is being
added continuously.
.PP
yq is written in go - so you can download a dependency free binary for
your platform and you are good to go! If you prefer there are a variety
of package managers that can be used as well as docker, all listed
below.
.SS Quick Usage Guide
.PP
Read a value:
.IP
.nf
\f[C]
yq e \[aq].a.b[0].c\[aq] file.yaml
\f[R]
.fi
.PP
Pipe from STDIN:
.IP
.nf
\f[C]
cat file.yaml | yq e \[aq].a.b[0].c\[aq] -
\f[R]
.fi
.PP
Update a yaml file, inplace
.IP
.nf
\f[C]
yq e -i \[aq].a.b[0].c = \[dq]cool\[dq]\[aq] file.yaml
\f[R]
.fi
.PP
Update using environment variables
.IP
.nf
\f[C]
NAME=mike yq e -i \[aq].a.b[0].c = strenv(NAME)\[aq] file.yaml
\f[R]
.fi
.PP
Merge multiple files
.IP
.nf
\f[C]
yq ea \[aq]. as $item ireduce ({}; . * $item )\[aq] path/to/*.yml
\f[R]
.fi
.PP
Multiple updates to a yaml file
.IP
.nf
\f[C]
yq e -i \[aq]
  .a.b[0].c = \[dq]cool\[dq] |
  .x.y.z = \[dq]foobar\[dq] |
  .person.name = strenv(NAME)
\[aq] file.yaml
\f[R]
.fi
.PP
See the documentation (https://mikefarah.gitbook.io/yq/) for more.
.SS Install
.SS Download the latest binary (https://github.com/mikefarah/yq/releases/latest)
.SS wget
.PP
Use wget to download the pre-compiled binaries:
.SS Compressed via tar.gz
.IP
.nf
\f[C]
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY}.tar.gz -O - |\[rs]
  tar xz && mv ${BINARY} /usr/bin/yq
\f[R]
.fi
.SS Plain binary
.IP
.nf
\f[C]
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY} -O /usr/bin/yq &&\[rs]
    chmod +x /usr/bin/yq
\f[R]
.fi
.PP
For instance, VERSION=v4.2.0 and BINARY=yq_linux_amd64
.SS MacOS / Linux via Homebrew:
.PP
Using Homebrew (https://brew.sh/)
.IP
.nf
\f[C]
brew install yq
\f[R]
.fi
.PP
or, for the (deprecated) v3 version:
.IP
.nf
\f[C]
brew install yq\[at]3
\f[R]
.fi
.PP
Note that for v3, as it is a versioned brew it will not add the
\f[C]yq\f[R] command to your path automatically.
Please follow the instructions given by brew upon installation.
.SS Linux via snap:
.IP
.nf
\f[C]
snap install yq
\f[R]
.fi
.PP
or, for the (deprecated) v3 version:
.IP
.nf
\f[C]
snap install yq --channel=v3/stable
\f[R]
.fi
.SS Snap notes
.PP
\f[C]yq\f[R] installs with \f[I]strict
confinement\f[R] (https://docs.snapcraft.io/snap-confinement/6233) in
snap, this means it doesn\[cq]t have direct access to root files.
To read root files you can:
.IP
.nf
\f[C]
sudo cat /etc/myfile | yq e \[aq].a.path\[aq] - 
\f[R]
.fi
.PP
And to write to a root file you can either use
sponge (https://linux.die.net/man/1/sponge):
.IP
.nf
\f[C]
sudo cat /etc/myfile | yq e \[aq].a.path = \[dq]value\[dq]\[aq] - | sudo sponge /etc/myfile
\f[R]
.fi
.PP
or write to a temporary file:
.IP
.nf
\f[C]
sudo cat /etc/myfile | yq e \[aq].a.path = \[dq]value\[dq]\[aq] | sudo tee /etc/myfile.tmp
sudo mv /etc/myfile.tmp /etc/myfile
rm /etc/myfile.tmp
\f[R]
.fi
.SS Run with Docker
.SS Oneshot use:
.IP
.nf
\f[C]
docker run --rm -v \[dq]${PWD}\[dq]:/workdir mikefarah/yq <command> [flags] [expression ]FILE...
\f[R]
.fi
.SS Pipe in via STDIN:
.PP
You\[cq]ll need to pass the \f[C]-i\[rs]--interactive\f[R] flag to
docker:
.IP
.nf
\f[C]
cat myfile.yml | docker run -i --rm mikefarah/yq e . -
\f[R]
.fi
.SS Run commands interactively:
.IP
.nf
\f[C]
docker run --rm -it -v \[dq]${PWD}\[dq]:/workdir --entrypoint sh mikefarah/yq
\f[R]
.fi
.PP
It can be useful to have a bash function to avoid typing the whole
docker command:
.IP
.nf
\f[C]
yq() {
  docker run --rm -i -v \[dq]${PWD}\[dq]:/workdir mikefarah/yq \[dq]$\[at]\[dq]
}
\f[R]
.fi
.SS Running as root:
.PP
\f[C]yq\f[R]\[cq]s docker image no longer runs under root
(https://github.com/mikefarah/yq/pull/860).
If you\[cq]d like to install more things in the docker image, or
you\[cq]re having permissions issues when attempting to read/write files
you\[cq]ll need to either:
.IP
.nf
\f[C]
docker run --user=\[dq]root\[dq] -it --entrypoint sh mikefarah/yq
\f[R]
.fi
.PP
Or, in your docker file:
.IP
.nf
\f[C]
FROM mikefarah/yq

USER root
RUN apk add bash
USER yq
\f[R]
.fi
.SS GitHub Action
.IP
.nf
\f[C]
  - name: Set foobar to cool
    uses: mikefarah/yq\[at]master
    with:
      cmd: yq eval -i \[aq].foo.bar = \[dq]cool\[dq]\[aq] \[aq]config.yml\[aq]
\f[R]
.fi
.PP
See https://mikefarah.gitbook.io/yq/usage/github-action for more.
.SS Go Get:
.IP
.nf
\f[C]
GO111MODULE=on go get github.com/mikefarah/yq/v4
\f[R]
.fi
.SS Community Supported Installation methods
.PP
As these are supported by the community :heart: - however, they may be
out of date with the officially supported releases.
.SH Webi
.IP
.nf
\f[C]
webi yq
\f[R]
.fi
.PP
See webi (https://webinstall.dev/) Supported by \[at]adithyasunil26
(https://github.com/webinstall/webi-installers/tree/master/yq)
.SS Windows:
.PP
[IMAGE: Chocolatey (https://img.shields.io/chocolatey/v/yq.svg)] (https://chocolatey.org/packages/yq)
[IMAGE: Chocolatey (https://img.shields.io/chocolatey/dt/yq.svg)] (https://chocolatey.org/packages/yq)
.IP
.nf
\f[C]
choco install yq
\f[R]
.fi
.PP
Supported by \[at]chillum (https://chocolatey.org/packages/yq)
.SS Mac:
.PP
Using MacPorts (https://www.macports.org/)
.IP
.nf
\f[C]
sudo port selfupdate
sudo port install yq
\f[R]
.fi
.PP
Supported by \[at]herbygillot
(https://ports.macports.org/maintainer/github/herbygillot)
.SS Alpine Linux
.IP \[bu] 2
Enable edge/community repo by adding
\f[C]$MIRROR/alpine/edge/community\f[R] to
\f[C]/etc/apk/repositories\f[R]
.IP \[bu] 2
Update database index with \f[C]apk update\f[R]
.IP \[bu] 2
Install yq with \f[C]apk add yq\f[R]
.PP
Supported by Tuan Hoang
https://pkgs.alpinelinux.org/package/edge/community/x86/yq
.SS On Ubuntu 16.04 or higher from Debian package:
.IP
.nf
\f[C]
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
\f[R]
.fi
.PP
Supported by \[at]rmescandon
(https://launchpad.net/\[ti]rmescandon/+archive/ubuntu/yq)
.SS Features
.IP \[bu] 2
Detailed documentation with many
examples (https://mikefarah.gitbook.io/yq/)
.IP \[bu] 2
Written in portable go, so you can download a lovely dependency free
binary
.IP \[bu] 2
Uses similar syntax as \f[C]jq\f[R] but works with YAML and JSON files
.IP \[bu] 2
Fully supports multi document yaml files
.IP \[bu] 2
Supports yaml front
matter (https://mikefarah.gitbook.io/yq/usage/front-matter) blocks
(e.g.\ jekyll/assemble)
.IP \[bu] 2
Colorized yaml output
.IP \[bu] 2
Deeply traverse
yaml (https://mikefarah.gitbook.io/yq/operators/traverse-read)
.IP \[bu] 2
Sort yaml by keys (https://mikefarah.gitbook.io/yq/operators/sort-keys)
.IP \[bu] 2
Manipulate yaml
comments (https://mikefarah.gitbook.io/yq/operators/comment-operators),
styling (https://mikefarah.gitbook.io/yq/operators/style),
tags (https://mikefarah.gitbook.io/yq/operators/tag) and anchors and
aliases (https://mikefarah.gitbook.io/yq/operators/anchor-and-alias-operators).
.IP \[bu] 2
Update yaml
inplace (https://mikefarah.gitbook.io/yq/v/v4.x/commands/evaluate#flags)
.IP \[bu] 2
Complex expressions to select and
update (https://mikefarah.gitbook.io/yq/operators/select#select-and-update-matching-values-in-map)
.IP \[bu] 2
Keeps yaml formatting and comments when updating (though there are
issues with whitespace)
.IP \[bu] 2
Convert to/from
json (https://mikefarah.gitbook.io/yq/v/v4.x/usage/convert)
.IP \[bu] 2
Convert to
properties (https://mikefarah.gitbook.io/yq/v/v4.x/usage/properties)
.IP \[bu] 2
Pipe data in by using
`-' (https://mikefarah.gitbook.io/yq/v/v4.x/commands/evaluate)
.IP \[bu] 2
General shell completion scripts
(bash/zsh/fish/powershell) (https://mikefarah.gitbook.io/yq/v/v4.x/commands/shell-completion)
.IP \[bu] 2
Reduce (https://mikefarah.gitbook.io/yq/operators/reduce) to merge
multiple files or sum an array or other fancy things.
.IP \[bu] 2
Github Action (https://mikefarah.gitbook.io/yq/usage/github-action) to
use in your automated pipeline (thanks \[at]devorbitus)
.SS Usage (https://mikefarah.gitbook.io/yq/)
.PP
Check out the documentation (https://mikefarah.gitbook.io/yq/) for more
detailed and advanced usage.
.IP
.nf
\f[C]
Usage:
  yq [flags]
  yq [command]

Available Commands:
  eval             Apply the expression to each document in each yaml file in sequence
  eval-all         Loads _all_ yaml documents of _all_ yaml files and runs expression once
  help             Help about any command
  shell-completion Generate completion script

Flags:
  -C, --colors                force print with colors
  -e, --exit-status           set exit status if there are no matches or null or false is returned
  -f, --front-matter string   (extract|process) first input as yaml front-matter. Extract will pull out the yaml content, process will run the expression against the yaml content, leaving the remaining data intact
  -h, --help                  help for yq
  -I, --indent int            sets indent level for output (default 2)
  -i, --inplace               update the yaml file inplace of first yaml file given.
  -M, --no-colors             force print with no colors
  -N, --no-doc                Don\[aq]t print document separators (---)
  -n, --null-input            Don\[aq]t read input, simply evaluate the expression given. Useful for creating yaml docs from scratch.
  -P, --prettyPrint           pretty print, shorthand for \[aq]... style = \[dq]\[dq]\[aq]
  -j, --tojson                output as json. Set indent to 0 to print json in one line.
      --unwrapScalar          unwrap scalar, print the value with no quotes, colors or comments (default true)
  -v, --verbose               verbose mode
  -V, --version               Print version information and quit

Use \[dq]yq [command] --help\[dq] for more information about a command.
\f[R]
.fi
.SS Known Issues / Missing Features
.IP \[bu] 2
\f[C]yq\f[R] 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)
.IP \[bu] 2
Powershell has its own\&...opinions:
https://mikefarah.gitbook.io/yq/usage/tips-and-tricks#quotes-in-windows-powershell
.PP
See tips and
tricks (https://mikefarah.gitbook.io/yq/usage/tips-and-tricks) for more
common problems and solutions.