yq(1)
yq is a lightweight YAML, JSON, XML and CSV query and transformation tool that works like jq but for structured data formats.
Synopsis
yq [FLAGS] [EXPRESSION] [FILE]...Description
yq is a command-line YAML processor that lets you query, filter, update, and transform YAML documents. It uses an expression syntax similar to jq, making it intuitive for those familiar with JSON querying. It also handles JSON, XML, and CSV formats transparently.
You can use yq to extract values, modify structure, merge documents, and convert between formats. It's commonly used in scripts, CI/CD pipelines, and configuration management workflows.
Common options
| Flag | What it does |
|---|---|
-r, --raw-output | Output raw strings without quotes; useful for shell integration |
-y, --yaml-output | Output results in YAML format (default for most operations) |
-j, --json-output | Output results in JSON format |
-x, --xml-output | Output results in XML format |
-c, --compact-output | Compact JSON output (no pretty-printing) |
-i, --inplace | Modify files in-place instead of printing to stdout |
-s, --slurp | Read entire input stream into array before processing |
-n, --null-input | Don't read input; useful for generating new documents |
-M, --no-colors | Disable colored output |
-e, --exit-status | Set exit code based on output (0 if truthy, 1 if false/null) |
Examples
Extract the 'name' field from a YAML file
yq '.name' config.yamlFilter array items where status equals 'active'
yq '.items[] | select(.status == "active")' data.yamlUpdate a nested value in-place
yq '.database.host = "localhost"' config.yaml -iExtract all email addresses as raw strings from an array
yq -r '.users[].email' users.yamlExtract config object and output as JSON
yq -j '.config' data.yamlMerge multiple YAML files by slurping them into an array and adding
yq -s 'add' *.yamlGenerate a new YAML document from scratch
yq -n '{name: "app", version: "1.0"}' -yRead JSON from stdin, filter, and output as YAML
cat data.json | yq '.[] | select(.id > 5)' -y