yq: Usage, Options & Common CI Errors

yq reads and edits YAML (and JSON/XML) the way jq handles JSON.

yq is the go-to for editing YAML manifests in pipelines. The big trap is version skew: the Go yq (mikefarah) and the Python yq are different tools with different syntax.

What it does

yq evaluates an expression against a YAML/JSON/XML document and prints or edits the result. The widely used Go implementation (mikefarah/yq v4) uses jq-style path expressions.

Common usage

Terminal

yq '.metadata.name' deploy.yaml
yq -i '.spec.replicas = 3' deploy.yaml        # edit in place
yq -o=json '.' config.yaml                     # YAML -> JSON
yq '.images[] | .tag' values.yaml
VALUE=ci yq -i '.env = strenv(VALUE)' file.yaml

Options

Flag	What it does
-i / --inplace	Edit the file in place
-o=json\|yaml\|xml	Set output format
-P / --prettyPrint	Pretty-print output
-r / --raw-output	Emit unquoted scalars (Python yq)
eval / eval-all	Evaluate one / merge multiple docs (v4)

Common errors in CI

Syntax that "works locally" but fails in CI is almost always a version mismatch: the Python yq (a jq wrapper) needs yq -r ".x" while the Go yq v4 uses yq ".x". "Error: unknown shorthand flag" usually means the other implementation is installed. Pin the binary explicitly (download mikefarah/yq) and use strenv()/env() to inject variables rather than shell interpolation.

Related guides

jq: Usage, Options & Common CI Errorsjq is a command-line JSON processor. Reference for -r, -e, filters, --arg, and the parse errors and "null" su… sed: Usage, Options & Common CI Errorssed is a stream editor for filtering and transforming text. Reference for -i, -e, -E, s///, and the GNU-vs-BS… envsubst: Usage, Options & Common CI Errorsenvsubst substitutes environment variables into text templates. Reference for variable lists, stdin/stdout us… cat: Usage, Options & Common CI Errorscat concatenates and prints files and writes here-docs. Reference for -n, -A, heredocs, and the "No such file…