yq eval: The Default Single-Document Command

yq eval evaluates an expression against each document separately and is what yq runs when you give no subcommand.

In yq v4, eval is the default verb. yq '.a' f.yaml and yq eval '.a' f.yaml are the same command. Knowing eval exists matters when you reach for its options.

What it does

yq eval applies the expression to one document at a time. When a file holds several --- separated documents, the expression runs once per document independently. yq with no subcommand is shorthand for yq eval.

Common usage

Terminal

yq eval '.metadata.name' deploy.yaml
yq '.metadata.name' deploy.yaml          # identical (eval is default)
yq eval -n '.a.b = "x"'                   # build a doc from null input

eval flags

Flag	What it does
(none)	eval is the default subcommand
-n / --null-input	Start from null instead of reading input
-i / --inplace	Write the result back to the file
-e / --exit-status	Exit non-zero if the result is null or false
-N / --no-doc	Do not print the --- document separator

In CI

Use eval -n to synthesize a small config without a template file: yq -n '.replicas = env(N)' > out.yaml. Use eval (not eval-all) when each document should be processed on its own; reach for eval-all only when you need all documents in scope at once.

Common errors in CI

Running eval over a multi-doc file and expecting cross-document access (like indexing document 2 from document 0) fails because eval sees one document at a time; that is what eval-all is for. "Error: bad file ... yaml: line N" usually means the input was JSON-with-tabs or not valid YAML. On Python yq there is no eval subcommand at all, so yq eval '.a' errors, a clear sign of the wrong implementation.