# yq — Process YAML and JSON on the Command Line > Practical guide to yq (mikefarah): query, transform and edit YAML, JSON and XML on the command line with a jq-like syntax. Source: https://www.jpkc.com/db/en/cheatsheets/files-text/yq/ yq is a lightweight command-line processor for structured data – think `jq`, but primarily for YAML (plus JSON, XML, CSV, TOML and properties). Pay attention to which yq you have installed: this guide targets the Go-based **mikefarah/yq** with its own jq-like expression syntax (`yq eval`, `yq '.foo'`, `-i` for in-place editing, `-o=json` for output). The older **kislyuk/yq** is a Python wrapper around `jq` and uses a different syntax, so the examples below won't work there as written. With yq you read values, filter lists, edit files in place and convert between formats, slotting cleanly into pipelines with tools like `kubectl` or `docker compose`. ## Read & Query `yq ` — Pretty-print a YAML file. ```bash yq config.yaml ``` `yq '.' ` — Read a specific key. ```bash yq '.server.port' config.yaml ``` `yq '..' ` — Read a nested value. ```bash yq '.database.connection.host' config.yaml ``` `yq '.[]' ` — Read an array element by index. ```bash yq '.services[0].name' docker-compose.yml ``` `yq '.[]' ` — Iterate over all array elements. ```bash yq '.users[].email' config.yaml ``` `yq '.[] | key' ` — List all top-level keys. ```bash yq '.[] | key' config.yaml ``` ## Modify & Update `yq '. = ""' ` — Set a value (outputs to stdout). ```bash yq '.server.port = 8080' config.yaml ``` `yq -i '. = ""' ` — Set a value in-place (modifies the file). ```bash yq -i '.version = "2.0.0"' config.yaml ``` `yq '. += ""' ` — Append a value to an array. ```bash yq -i '.tags += ["new-tag"]' config.yaml ``` `yq 'del(.)' ` — Delete a key. ```bash yq -i 'del(.deprecated_setting)' config.yaml ``` `yq '. |= . + 1' ` — Increment a numeric value. ```bash yq -i '.build_number |= . + 1' version.yaml ``` ## Filter & Select `yq '.[] | select(. == "")' ` — Select elements matching a condition. ```bash yq '.users[] | select(.role == "admin")' users.yaml ``` `yq '.[] | select(. > )' ` — Select elements with numeric comparison. ```bash yq '.items[] | select(.price > 100)' catalog.yaml ``` `yq '. | length' ` — Count elements in an array. ```bash yq '.services | length' docker-compose.yml ``` `yq '.[] | keys' ` — List keys of a map. ```bash yq '.services | keys' docker-compose.yml ``` `yq 'has("")' ` — Check if a key exists. ```bash yq 'has("database")' config.yaml ``` ## Format Conversion `yq -o=json ` — Convert YAML to JSON. ```bash yq -o=json config.yaml > config.json ``` `yq -p=json ` — Read JSON input and output as YAML. ```bash yq -p=json config.json > config.yaml ``` `yq -p=json -o=yaml ` — Convert JSON to YAML (explicit). ```bash yq -p=json -o=yaml package.json ``` `yq -o=xml ` — Convert YAML to XML. ```bash yq -o=xml config.yaml ``` `yq -o=csv ` — Convert YAML to CSV. ```bash yq -o=csv '.users' data.yaml ``` `yq -o=props ` — Convert YAML to Java properties format. ```bash yq -o=props config.yaml ``` ## Merge & Multi-Document `yq '. * load("")' ` — Deep merge two YAML files (second overrides first). ```bash yq '. * load("overrides.yaml")' base.yaml ``` `yq eval-all '. as $item ireduce ({}; . * $item)' ` — Merge multiple files together. ```bash yq eval-all '. as $item ireduce ({}; . * $item)' defaults.yaml env.yaml ``` `yq -s '"doc_" + $index' ` — Split a multi-document YAML into separate files. ```bash yq -s '"doc_" + $index' multi.yaml ``` `yq 'select(documentIndex == 0)' ` — Select a specific document from a multi-doc YAML. ```bash yq 'select(documentIndex == 0)' multi.yaml ``` ## Piping & Common Patterns `cat | yq '.'` — Read from stdin. ```bash kubectl get pod mypod -o yaml | yq '.metadata.labels' ``` `yq -r '.' ` — Raw output (no quotes around strings). ```bash yq -r '.image' deployment.yaml ``` `yq -i '.image = "nginx:1.25"' deployment.yaml` — Update a container image version in a Kubernetes manifest. ```bash yq -i '.spec.template.spec.containers[0].image = "nginx:1.25"' deployment.yaml ``` `yq '.env_file' docker-compose.yml` — Inspect Docker Compose config from the command line. ```bash yq '.services.web.environment' docker-compose.yml ``` ## Conclusion yq makes reading and reshaping YAML, JSON and friends on the command line as convenient as `jq` is for JSON – perfect for pipelines with `kubectl`, `docker compose` or CI scripts. Keep in mind, though, that every example here targets **mikefarah/yq** (Go); with the Python wrapper **kislyuk/yq** many expressions look different. Take particular care with `-i` (in-place): yq overwrites the file directly and without prompting – make a backup first or work under version control, and test new expressions without `-i` by checking the output on stdout first. Note too that while yq largely preserves comments and formatting when editing in place, it may still normalize the file. ## Further Reading - [mikefarah/yq documentation](https://mikefarah.gitbook.io/yq/) – the official manual with every operator and plenty of examples - [mikefarah/yq on GitHub](https://github.com/mikefarah/yq) – source code, installation instructions and release notes ## Related Commands - [jq](https://www.jpkc.com/db/en/cheatsheets/files-text/jq/) – the counterpart to yq for JSON data - [sed](https://www.jpkc.com/db/en/cheatsheets/files-text/sed/) – stream editor for line-based text manipulation - [grep](https://www.jpkc.com/db/en/cheatsheets/files-text/grep/) – search text for patterns